From 983a7dbfc4cb27b515079234ce285754de6476b4 Mon Sep 17 00:00:00 2001
From: Austin Gill <Notgnoshi@gmail.com>
Date: Fri, 20 Feb 2026 17:20:50 -0600
Subject: [PATCH 1/6] Upgrade petgraph to 0.8

---
 Cargo.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Cargo.toml b/Cargo.toml
index 28fe422..8c43aa9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -35,7 +35,7 @@ mermaid-rs-renderer = { version = "0.1.2", default-features = false }
 itertools-num = "0.1.3"
 kernel-density-estimation = "0.2.0"
 ordered-float = "5.0.0"
-petgraph = "0.7"
+petgraph = "0.8"
 regex = "1"
 pathdiff = "0.2.3"
 serde = { version = "1.0.217", features = ["derive"] }

From f23a1712b19a7feb3cf33bf764c7f5d4bf5ae432 Mon Sep 17 00:00:00 2001
From: Austin Gill <Notgnoshi@gmail.com>
Date: Fri, 20 Feb 2026 17:27:58 -0600
Subject: [PATCH 2/6] Add graphdiff tool

---
 crates/csvizmo-depgraph/src/algorithm/diff.rs | 846 ++++++++++++++++++
 crates/csvizmo-depgraph/src/algorithm/mod.rs  |   1 +
 crates/csvizmo-depgraph/src/bin/graphdiff.rs  | 169 ++++
 crates/csvizmo-depgraph/tests/graphdiff.rs    | 605 +++++++++++++
 4 files changed, 1621 insertions(+)
 create mode 100644 crates/csvizmo-depgraph/src/algorithm/diff.rs
 create mode 100644 crates/csvizmo-depgraph/src/bin/graphdiff.rs
 create mode 100644 crates/csvizmo-depgraph/tests/graphdiff.rs

diff --git a/crates/csvizmo-depgraph/src/algorithm/diff.rs b/crates/csvizmo-depgraph/src/algorithm/diff.rs
new file mode 100644
index 0000000..4181eca
--- /dev/null
+++ b/crates/csvizmo-depgraph/src/algorithm/diff.rs
@@ -0,0 +1,846 @@
+use std::collections::HashSet;
+use std::io::Write;
+
+use indexmap::IndexMap;
+
+use crate::{DepGraph, Edge, NodeInfo};
+
+/// Status of a node or edge in a graph diff.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DiffStatus {
+    Added,
+    Removed,
+    Changed,
+    Moved,
+    Unchanged,
+}
+
+/// A node with its diff status.
+#[derive(Debug)]
+pub struct DiffNode {
+    pub status: DiffStatus,
+    pub info: NodeInfo,
+}
+
+/// An edge with its diff status.
+#[derive(Debug)]
+pub struct DiffEdge {
+    pub status: DiffStatus,
+    pub edge: Edge,
+}
+
+/// Result of diffing two dependency graphs.
+#[derive(Debug)]
+pub struct GraphDiff {
+    pub nodes: IndexMap<String, DiffNode>,
+    pub edges: Vec<DiffEdge>,
+}
+
+impl GraphDiff {
+    /// Returns true if any node or edge has a status other than Unchanged.
+    pub fn has_changes(&self) -> bool {
+        self.nodes
+            .values()
+            .any(|n| n.status != DiffStatus::Unchanged)
+            || self.edges.iter().any(|e| e.status != DiffStatus::Unchanged)
+    }
+}
+
+fn node_eq(a: &NodeInfo, b: &NodeInfo) -> bool {
+    a.label == b.label && a.node_type == b.node_type && a.attrs == b.attrs
+}
+
+fn edge_eq(a: &Edge, b: &Edge) -> bool {
+    a.label == b.label && a.attrs == b.attrs
+}
+
+fn build_incoming(edges: &[Edge]) -> IndexMap<String, Vec<String>> {
+    let mut incoming: IndexMap<String, Vec<String>> = IndexMap::new();
+    for edge in edges {
+        incoming
+            .entry(edge.to.clone())
+            .or_default()
+            .push(edge.from.clone());
+    }
+    incoming
+}
+
+/// Compute the difference between two dependency graphs.
+///
+/// Nodes are matched by ID. Edges are matched by (from, to) tuple.
+/// Content equality for nodes compares label, node_type, and attrs.
+/// Content equality for edges compares label and attrs.
+/// Nodes that are unchanged in content but have a single parent that
+/// changed are marked as Moved.
+pub fn diff(before: &DepGraph, after: &DepGraph) -> GraphDiff {
+    let before_nodes = before.all_nodes();
+    let after_nodes = after.all_nodes();
+    let before_edges = before.all_edges();
+    let after_edges = after.all_edges();
+
+    let mut nodes = IndexMap::new();
+
+    // After-graph nodes: Added, Changed, or Unchanged
+    for (id, after_info) in after_nodes {
+        let status = match before_nodes.get(id) {
+            Some(before_info) => {
+                if node_eq(before_info, after_info) {
+                    DiffStatus::Unchanged
+                } else {
+                    DiffStatus::Changed
+                }
+            }
+            None => DiffStatus::Added,
+        };
+        nodes.insert(
+            id.clone(),
+            DiffNode {
+                status,
+                info: after_info.clone(),
+            },
+        );
+    }
+
+    // Before-only nodes: Removed
+    for (id, before_info) in before_nodes {
+        if !after_nodes.contains_key(id) {
+            nodes.insert(
+                id.clone(),
+                DiffNode {
+                    status: DiffStatus::Removed,
+                    info: before_info.clone(),
+                },
+            );
+        }
+    }
+
+    // Build before-edge lookup grouped by (from, to), consuming matched entries as we go
+    let mut before_edge_map: IndexMap<(String, String), Vec<Edge>> = IndexMap::new();
+    for edge in before_edges {
+        let key = (edge.from.clone(), edge.to.clone());
+        before_edge_map.entry(key).or_default().push(edge.clone());
+    }
+
+    let mut edges = Vec::new();
+
+    for edge in after_edges {
+        let key = (edge.from.clone(), edge.to.clone());
+        let status = match before_edge_map.get_mut(&key) {
+            Some(before_edges) => {
+                if let Some(pos) = before_edges.iter().position(|be| edge_eq(be, edge)) {
+                    before_edges.swap_remove(pos);
+                    DiffStatus::Unchanged
+                } else if !before_edges.is_empty() {
+                    before_edges.swap_remove(0);
+                    DiffStatus::Changed
+                } else {
+                    DiffStatus::Added
+                }
+            }
+            None => DiffStatus::Added,
+        };
+        edges.push(DiffEdge {
+            status,
+            edge: edge.clone(),
+        });
+    }
+
+    // Remaining before edges are Removed
+    for (_, remaining) in before_edge_map {
+        for edge in remaining {
+            edges.push(DiffEdge {
+                status: DiffStatus::Removed,
+                edge,
+            });
+        }
+    }
+
+    // Move detection: upgrade Unchanged nodes whose single parent changed
+    let before_incoming = build_incoming(before_edges);
+    let after_incoming = build_incoming(after_edges);
+
+    for (id, diff_node) in &mut nodes {
+        if diff_node.status != DiffStatus::Unchanged {
+            continue;
+        }
+        let before_parents = before_incoming.get(id.as_str());
+        let after_parents = after_incoming.get(id.as_str());
+        match (before_parents, after_parents) {
+            (Some(bp), Some(ap)) if bp.len() == 1 && ap.len() == 1 && bp[0] != ap[0] => {
+                diff_node.status = DiffStatus::Moved;
+            }
+            _ => {}
+        }
+    }
+
+    GraphDiff { nodes, edges }
+}
+
+/// Build an annotated graph combining both inputs with visual diff styling.
+///
+/// Added nodes/edges are green, removed are red, changed are orange,
+/// moved are blue. Each element gets a `diff` attribute for programmatic
+/// filtering. The after-graph's subgraph structure is preserved: nodes
+/// appear in their original subgraph positions. Removed nodes (only in
+/// the before-graph) are placed at root level, or into a `cluster_removed`
+/// subgraph when `cluster` is true.
+pub fn annotate_graph(diff: &GraphDiff, after: &DepGraph, cluster: bool) -> DepGraph {
+    fn annotate_node(diff_node: &DiffNode) -> NodeInfo {
+        let mut info = diff_node.info.clone();
+        match diff_node.status {
+            DiffStatus::Added => {
+                info.label = format!("+ {}", info.label);
+                info.attrs.insert("color".into(), "green".into());
+                info.attrs.insert("fontcolor".into(), "green".into());
+                info.attrs.insert("diff".into(), "added".into());
+            }
+            DiffStatus::Removed => {
+                info.label = format!("- {}", info.label);
+                info.attrs.insert("color".into(), "red".into());
+                info.attrs.insert("fontcolor".into(), "red".into());
+                info.attrs.insert("diff".into(), "removed".into());
+            }
+            DiffStatus::Changed => {
+                info.label = format!("~ {}", info.label);
+                info.attrs.insert("color".into(), "orange".into());
+                info.attrs.insert("fontcolor".into(), "orange".into());
+                info.attrs.insert("diff".into(), "changed".into());
+            }
+            DiffStatus::Moved => {
+                info.label = format!("> {}", info.label);
+                info.attrs.insert("color".into(), "blue".into());
+                info.attrs.insert("fontcolor".into(), "blue".into());
+                info.attrs.insert("diff".into(), "moved".into());
+            }
+            DiffStatus::Unchanged => {
+                info.attrs.insert("diff".into(), "unchanged".into());
+            }
+        }
+        info
+    }
+
+    fn annotate_subgraph(diff: &GraphDiff, subgraph: &DepGraph) -> DepGraph {
+        let nodes: IndexMap<String, NodeInfo> = subgraph
+            .nodes
+            .keys()
+            .filter_map(|id| {
+                let diff_node = diff.nodes.get(id)?;
+                Some((id.clone(), annotate_node(diff_node)))
+            })
+            .collect();
+
+        let subgraphs: Vec<DepGraph> = subgraph
+            .subgraphs
+            .iter()
+            .map(|sg| annotate_subgraph(diff, sg))
+            .filter(|sg| !sg.nodes.is_empty() || !sg.subgraphs.is_empty())
+            .collect();
+
+        DepGraph {
+            id: subgraph.id.clone(),
+            attrs: subgraph.attrs.clone(),
+            nodes,
+            subgraphs,
+            ..Default::default()
+        }
+    }
+
+    // Walk the after-graph tree to place nodes in their original positions.
+    let mut root = annotate_subgraph(diff, after);
+
+    // Removed nodes are not in the after-graph; collect them separately.
+    let removed_nodes: IndexMap<String, NodeInfo> = diff
+        .nodes
+        .iter()
+        .filter(|(_, n)| n.status == DiffStatus::Removed)
+        .map(|(id, n)| (id.clone(), annotate_node(n)))
+        .collect();
+
+    if !removed_nodes.is_empty() {
+        if cluster {
+            root.subgraphs.push(DepGraph {
+                id: Some("cluster_removed".into()),
+                nodes: removed_nodes,
+                ..Default::default()
+            });
+        } else {
+            root.nodes.extend(removed_nodes);
+        }
+    }
+
+    // Edges stay at root level.
+    for diff_edge in &diff.edges {
+        let mut edge = diff_edge.edge.clone();
+        match diff_edge.status {
+            DiffStatus::Added => {
+                edge.attrs.insert("color".into(), "green".into());
+                edge.attrs.insert("diff".into(), "added".into());
+            }
+            DiffStatus::Removed => {
+                edge.attrs.insert("color".into(), "red".into());
+                edge.attrs.insert("diff".into(), "removed".into());
+            }
+            DiffStatus::Changed => {
+                edge.attrs.insert("color".into(), "orange".into());
+                edge.attrs.insert("diff".into(), "changed".into());
+            }
+            DiffStatus::Moved => {
+                edge.attrs.insert("color".into(), "blue".into());
+                edge.attrs.insert("diff".into(), "moved".into());
+            }
+            DiffStatus::Unchanged => {
+                edge.attrs.insert("diff".into(), "unchanged".into());
+            }
+        }
+        root.edges.push(edge);
+    }
+
+    root
+}
+
+/// Build a graph containing only nodes exclusive to the "before" graph.
+///
+/// The before-graph's subgraph structure is preserved. Edges are included
+/// only when both endpoints are removed nodes. Empty subgraphs are dropped.
+pub fn subtract_graph(diff: &GraphDiff, before: &DepGraph) -> DepGraph {
+    let removed_ids: HashSet<&str> = diff
+        .nodes
+        .iter()
+        .filter(|(_, n)| n.status == DiffStatus::Removed)
+        .map(|(id, _)| id.as_str())
+        .collect();
+
+    fn filter_subgraph(graph: &DepGraph, keep: &HashSet<&str>) -> DepGraph {
+        DepGraph {
+            id: graph.id.clone(),
+            attrs: graph.attrs.clone(),
+            nodes: graph
+                .nodes
+                .iter()
+                .filter(|(id, _)| keep.contains(id.as_str()))
+                .map(|(id, info)| (id.clone(), info.clone()))
+                .collect(),
+            edges: graph
+                .edges
+                .iter()
+                .filter(|e| keep.contains(e.from.as_str()) && keep.contains(e.to.as_str()))
+                .cloned()
+                .collect(),
+            subgraphs: graph
+                .subgraphs
+                .iter()
+                .map(|sg| filter_subgraph(sg, keep))
+                .filter(|sg| !sg.nodes.is_empty() || !sg.subgraphs.is_empty())
+                .collect(),
+            ..Default::default()
+        }
+    }
+
+    filter_subgraph(before, &removed_ids)
+}
+
+/// Write a tab-delimited listing of changed nodes and edges.
+///
+/// Unchanged items are omitted. Node format: `<status>\t<id>\t<label>`
+/// (label column omitted when it equals the ID). Edge format:
+/// `<status>\t<from>\t<to>`.
+pub fn write_list(diff: &GraphDiff, writer: &mut dyn Write) -> eyre::Result<()> {
+    for (id, diff_node) in &diff.nodes {
+        let prefix = match diff_node.status {
+            DiffStatus::Added => "+",
+            DiffStatus::Removed => "-",
+            DiffStatus::Changed => "~",
+            DiffStatus::Moved => ">",
+            DiffStatus::Unchanged => continue,
+        };
+        if diff_node.info.label == *id {
+            writeln!(writer, "{prefix}\t{id}")?;
+        } else {
+            writeln!(writer, "{prefix}\t{id}\t{}", diff_node.info.label)?;
+        }
+    }
+    for diff_edge in &diff.edges {
+        let prefix = match diff_edge.status {
+            DiffStatus::Added => "+",
+            DiffStatus::Removed => "-",
+            DiffStatus::Changed => "~",
+            DiffStatus::Moved => ">",
+            DiffStatus::Unchanged => continue,
+        };
+        writeln!(
+            writer,
+            "{prefix}\t{}\t{}",
+            diff_edge.edge.from, diff_edge.edge.to
+        )?;
+    }
+    Ok(())
+}
+
+/// Write a tab-delimited summary of diff counts.
+pub fn write_summary(diff: &GraphDiff, writer: &mut dyn Write) -> eyre::Result<()> {
+    let (mut added_n, mut removed_n, mut changed_n, mut moved_n, mut unchanged_n) =
+        (0usize, 0, 0, 0, 0);
+    for n in diff.nodes.values() {
+        match n.status {
+            DiffStatus::Added => added_n += 1,
+            DiffStatus::Removed => removed_n += 1,
+            DiffStatus::Changed => changed_n += 1,
+            DiffStatus::Moved => moved_n += 1,
+            DiffStatus::Unchanged => unchanged_n += 1,
+        }
+    }
+
+    let (mut added_e, mut removed_e, mut changed_e, mut unchanged_e) = (0usize, 0, 0, 0);
+    for e in &diff.edges {
+        match e.status {
+            DiffStatus::Added => added_e += 1,
+            DiffStatus::Removed => removed_e += 1,
+            DiffStatus::Changed => changed_e += 1,
+            DiffStatus::Moved | DiffStatus::Unchanged => unchanged_e += 1,
+        }
+    }
+
+    writeln!(writer, "added_nodes\t{added_n}")?;
+    writeln!(writer, "removed_nodes\t{removed_n}")?;
+    writeln!(writer, "changed_nodes\t{changed_n}")?;
+    writeln!(writer, "moved_nodes\t{moved_n}")?;
+    writeln!(writer, "unchanged_nodes\t{unchanged_n}")?;
+    writeln!(writer, "added_edges\t{added_e}")?;
+    writeln!(writer, "removed_edges\t{removed_e}")?;
+    writeln!(writer, "changed_edges\t{changed_e}")?;
+    writeln!(writer, "unchanged_edges\t{unchanged_e}")?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_graph(nodes: &[(&str, &str)], edges: &[(&str, &str)]) -> DepGraph {
+        DepGraph {
+            nodes: nodes
+                .iter()
+                .map(|(id, label)| (id.to_string(), NodeInfo::new(*label)))
+                .collect(),
+            edges: edges
+                .iter()
+                .map(|(from, to)| Edge {
+                    from: from.to_string(),
+                    to: to.to_string(),
+                    ..Default::default()
+                })
+                .collect(),
+            ..Default::default()
+        }
+    }
+
+    // -- diff --
+
+    #[test]
+    fn diff_identical() {
+        let g = make_graph(&[("a", "A"), ("b", "B")], &[("a", "b")]);
+        let result = diff(&g, &g);
+        assert!(
+            result
+                .nodes
+                .values()
+                .all(|n| n.status == DiffStatus::Unchanged)
+        );
+        assert!(
+            result
+                .edges
+                .iter()
+                .all(|e| e.status == DiffStatus::Unchanged)
+        );
+    }
+
+    #[test]
+    fn diff_disjoint() {
+        let before = make_graph(&[("a", "A")], &[]);
+        let after = make_graph(&[("b", "B")], &[]);
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["b"].status, DiffStatus::Added);
+        assert_eq!(result.nodes["a"].status, DiffStatus::Removed);
+    }
+
+    #[test]
+    fn diff_mixed() {
+        let before = make_graph(&[("a", "A"), ("b", "B")], &[("a", "b")]);
+        let after = make_graph(&[("b", "B"), ("c", "C")], &[("b", "c")]);
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["b"].status, DiffStatus::Unchanged);
+        assert_eq!(result.nodes["c"].status, DiffStatus::Added);
+        assert_eq!(result.nodes["a"].status, DiffStatus::Removed);
+    }
+
+    #[test]
+    fn diff_changed_label() {
+        let before = make_graph(&[("a", "Alpha")], &[]);
+        let after = make_graph(&[("a", "Aleph")], &[]);
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["a"].status, DiffStatus::Changed);
+        assert_eq!(result.nodes["a"].info.label, "Aleph");
+    }
+
+    #[test]
+    fn diff_changed_node_type() {
+        let mut before = make_graph(&[("a", "A")], &[]);
+        before.nodes.get_mut("a").unwrap().node_type = Some("lib".to_string());
+        let mut after = make_graph(&[("a", "A")], &[]);
+        after.nodes.get_mut("a").unwrap().node_type = Some("bin".to_string());
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["a"].status, DiffStatus::Changed);
+    }
+
+    #[test]
+    fn diff_changed_attrs() {
+        let mut before = make_graph(&[("a", "A")], &[]);
+        before
+            .nodes
+            .get_mut("a")
+            .unwrap()
+            .attrs
+            .insert("color".to_string(), "red".to_string());
+        let mut after = make_graph(&[("a", "A")], &[]);
+        after
+            .nodes
+            .get_mut("a")
+            .unwrap()
+            .attrs
+            .insert("color".to_string(), "blue".to_string());
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["a"].status, DiffStatus::Changed);
+    }
+
+    #[test]
+    fn diff_changed_edge() {
+        let mut before = make_graph(&[("a", "A"), ("b", "B")], &[]);
+        before.edges.push(Edge {
+            from: "a".to_string(),
+            to: "b".to_string(),
+            label: Some("uses".to_string()),
+            ..Default::default()
+        });
+        let mut after = make_graph(&[("a", "A"), ("b", "B")], &[]);
+        after.edges.push(Edge {
+            from: "a".to_string(),
+            to: "b".to_string(),
+            label: Some("depends".to_string()),
+            ..Default::default()
+        });
+        let result = diff(&before, &after);
+        assert_eq!(result.edges[0].status, DiffStatus::Changed);
+    }
+
+    #[test]
+    fn diff_duplicate_edges() {
+        let mut before = make_graph(&[("a", "A"), ("b", "B")], &[]);
+        before.edges.push(Edge {
+            from: "a".to_string(),
+            to: "b".to_string(),
+            label: Some("uses".to_string()),
+            ..Default::default()
+        });
+        before.edges.push(Edge {
+            from: "a".to_string(),
+            to: "b".to_string(),
+            label: Some("dev".to_string()),
+            ..Default::default()
+        });
+        let mut after = make_graph(&[("a", "A"), ("b", "B")], &[]);
+        after.edges.push(Edge {
+            from: "a".to_string(),
+            to: "b".to_string(),
+            label: Some("uses".to_string()),
+            ..Default::default()
+        });
+        after.edges.push(Edge {
+            from: "a".to_string(),
+            to: "b".to_string(),
+            label: Some("test".to_string()),
+            ..Default::default()
+        });
+        let result = diff(&before, &after);
+        // "uses" matched unchanged, "test" paired with "dev" as changed
+        assert_eq!(result.edges.len(), 2);
+        assert_eq!(result.edges[0].status, DiffStatus::Unchanged);
+        assert_eq!(result.edges[0].edge.label.as_deref(), Some("uses"));
+        assert_eq!(result.edges[1].status, DiffStatus::Changed);
+        assert_eq!(result.edges[1].edge.label.as_deref(), Some("test"));
+    }
+
+    #[test]
+    fn diff_empty() {
+        let result = diff(&DepGraph::default(), &DepGraph::default());
+        assert!(result.nodes.is_empty());
+        assert!(result.edges.is_empty());
+    }
+
+    // -- has_changes --
+
+    #[test]
+    fn has_changes_identical() {
+        let g = make_graph(&[("a", "A")], &[]);
+        let d = diff(&g, &g);
+        assert!(!d.has_changes());
+    }
+
+    #[test]
+    fn has_changes_different() {
+        let before = make_graph(&[("a", "A")], &[]);
+        let after = make_graph(&[("b", "B")], &[]);
+        let d = diff(&before, &after);
+        assert!(d.has_changes());
+    }
+
+    #[test]
+    fn has_changes_empty() {
+        let d = diff(&DepGraph::default(), &DepGraph::default());
+        assert!(!d.has_changes());
+    }
+
+    #[test]
+    fn diff_moved_node() {
+        // c has same info but different single parent
+        let before = make_graph(&[("p1", "P1"), ("c", "C")], &[("p1", "c")]);
+        let after = make_graph(&[("p2", "P2"), ("c", "C")], &[("p2", "c")]);
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["c"].status, DiffStatus::Moved);
+    }
+
+    #[test]
+    fn diff_multi_parent_not_moved() {
+        // c has multiple parents in both graphs -- not considered moved
+        let before = make_graph(
+            &[("p1", "P1"), ("p2", "P2"), ("c", "C")],
+            &[("p1", "c"), ("p2", "c")],
+        );
+        let after = make_graph(
+            &[("p1", "P1"), ("p3", "P3"), ("c", "C")],
+            &[("p1", "c"), ("p3", "c")],
+        );
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["c"].status, DiffStatus::Unchanged);
+    }
+
+    #[test]
+    fn diff_changed_and_moved_stays_changed() {
+        // c has different label AND different parent -- stays Changed
+        let before = make_graph(&[("p1", "P1"), ("c", "C")], &[("p1", "c")]);
+        let after = make_graph(&[("p2", "P2"), ("c", "C-new")], &[("p2", "c")]);
+        let result = diff(&before, &after);
+        assert_eq!(result.nodes["c"].status, DiffStatus::Changed);
+    }
+
+    // -- annotate_graph --
+
+    #[test]
+    fn annotate_identical() {
+        let g = make_graph(&[("a", "A")], &[]);
+        let d = diff(&g, &g);
+        let annotated = annotate_graph(&d, &g, false);
+        assert_eq!(annotated.nodes["a"].attrs["diff"], "unchanged");
+        assert_eq!(annotated.nodes["a"].label, "A");
+    }
+
+    #[test]
+    fn annotate_added_removed() {
+        let before = make_graph(&[("a", "A")], &[]);
+        let after = make_graph(&[("b", "B")], &[]);
+        let d = diff(&before, &after);
+        let annotated = annotate_graph(&d, &after, false);
+        assert_eq!(annotated.nodes["b"].label, "+ B");
+        assert_eq!(annotated.nodes["b"].attrs["color"], "green");
+        assert_eq!(annotated.nodes["b"].attrs["diff"], "added");
+        assert_eq!(annotated.nodes["a"].label, "- A");
+        assert_eq!(annotated.nodes["a"].attrs["color"], "red");
+        assert_eq!(annotated.nodes["a"].attrs["diff"], "removed");
+    }
+
+    #[test]
+    fn annotate_cluster() {
+        let before = make_graph(&[("a", "A")], &[]);
+        let after = make_graph(&[("b", "B")], &[]);
+        let d = diff(&before, &after);
+        let annotated = annotate_graph(&d, &after, true);
+        // Added nodes stay in their natural position (root of after-graph).
+        assert!(annotated.nodes.contains_key("b"));
+        // Only cluster_removed is created.
+        assert_eq!(annotated.subgraphs.len(), 1);
+        assert_eq!(
+            annotated.subgraphs[0].id.as_deref(),
+            Some("cluster_removed")
+        );
+        assert!(annotated.subgraphs[0].nodes.contains_key("a"));
+    }
+
+    #[test]
+    fn annotate_preserves_subgraphs() {
+        let sub = DepGraph {
+            id: Some("cluster_0".into()),
+            nodes: [("b".into(), NodeInfo::new("B"))].into_iter().collect(),
+            ..Default::default()
+        };
+        let after = DepGraph {
+            nodes: [("a".into(), NodeInfo::new("A"))].into_iter().collect(),
+            subgraphs: vec![sub],
+            ..Default::default()
+        };
+        let before = make_graph(&[("a", "A")], &[]);
+        let d = diff(&before, &after);
+        let annotated = annotate_graph(&d, &after, false);
+        // "a" unchanged at root, "b" added inside subgraph
+        assert!(annotated.nodes.contains_key("a"));
+        assert_eq!(annotated.subgraphs.len(), 1);
+        assert_eq!(annotated.subgraphs[0].id.as_deref(), Some("cluster_0"));
+        assert!(annotated.subgraphs[0].nodes.contains_key("b"));
+        assert_eq!(annotated.subgraphs[0].nodes["b"].attrs["diff"], "added");
+    }
+
+    // -- subtract_graph --
+
+    #[test]
+    fn subtract_only_removed() {
+        let before = make_graph(&[("a", "A"), ("b", "B")], &[("a", "b")]);
+        let after = make_graph(&[("b", "B")], &[]);
+        let d = diff(&before, &after);
+        let subtracted = subtract_graph(&d, &before);
+        assert_eq!(subtracted.nodes.len(), 1);
+        assert!(subtracted.nodes.contains_key("a"));
+        assert!(subtracted.edges.is_empty());
+    }
+
+    #[test]
+    fn subtract_with_edges() {
+        let before = make_graph(
+            &[("a", "A"), ("b", "B"), ("c", "C")],
+            &[("a", "b"), ("b", "c")],
+        );
+        let after = make_graph(&[("c", "C")], &[]);
+        let d = diff(&before, &after);
+        let subtracted = subtract_graph(&d, &before);
+        assert_eq!(subtracted.nodes.len(), 2);
+        assert!(subtracted.nodes.contains_key("a"));
+        assert!(subtracted.nodes.contains_key("b"));
+        assert_eq!(subtracted.edges.len(), 1);
+        assert_eq!(subtracted.edges[0].from, "a");
+        assert_eq!(subtracted.edges[0].to, "b");
+    }
+
+    #[test]
+    fn subtract_preserves_subgraphs() {
+        let sub = DepGraph {
+            id: Some("cluster_0".into()),
+            nodes: [("b".into(), NodeInfo::new("B"))].into_iter().collect(),
+            ..Default::default()
+        };
+        let before = DepGraph {
+            nodes: [("a".into(), NodeInfo::new("A"))].into_iter().collect(),
+            subgraphs: vec![sub],
+            ..Default::default()
+        };
+        // after has only "a", so "b" is removed
+        let after = make_graph(&[("a", "A")], &[]);
+        let d = diff(&before, &after);
+        let subtracted = subtract_graph(&d, &before);
+        // "b" should be in the subgraph, not at root
+        assert!(subtracted.nodes.is_empty());
+        assert_eq!(subtracted.subgraphs.len(), 1);
+        assert_eq!(subtracted.subgraphs[0].id.as_deref(), Some("cluster_0"));
+        assert!(subtracted.subgraphs[0].nodes.contains_key("b"));
+    }
+
+    // -- write_list --
+
+    #[test]
+    fn list_label_equals_id() {
+        let before = make_graph(&[("a", "a")], &[]);
+        let after = make_graph(&[("b", "b")], &[]);
+        let d = diff(&before, &after);
+        let mut buf = Vec::new();
+        write_list(&d, &mut buf).unwrap();
+        let output = String::from_utf8(buf).unwrap();
+        assert_eq!(output, "+\tb\n-\ta\n");
+    }
+
+    #[test]
+    fn list_with_labels() {
+        let before = make_graph(&[("a", "Alpha")], &[]);
+        let after = make_graph(&[("b", "Beta")], &[]);
+        let d = diff(&before, &after);
+        let mut buf = Vec::new();
+        write_list(&d, &mut buf).unwrap();
+        let output = String::from_utf8(buf).unwrap();
+        assert_eq!(output, "+\tb\tBeta\n-\ta\tAlpha\n");
+    }
+
+    #[test]
+    fn list_empty_diff() {
+        let g = make_graph(&[("a", "A")], &[]);
+        let d = diff(&g, &g);
+        let mut buf = Vec::new();
+        write_list(&d, &mut buf).unwrap();
+        let output = String::from_utf8(buf).unwrap();
+        assert_eq!(output, "");
+    }
+
+    #[test]
+    fn list_edges() {
+        let before = make_graph(&[("a", "a"), ("b", "b")], &[("a", "b")]);
+        let after = make_graph(&[("a", "a"), ("b", "b")], &[]);
+        let d = diff(&before, &after);
+        let mut buf = Vec::new();
+        write_list(&d, &mut buf).unwrap();
+        let output = String::from_utf8(buf).unwrap();
+        assert_eq!(output, "-\ta\tb\n");
+    }
+
+    // -- write_summary --
+
+    #[test]
+    fn summary_counts() {
+        let before = make_graph(&[("a", "A"), ("b", "B")], &[("a", "b")]);
+        let after = make_graph(&[("b", "B-new"), ("c", "C")], &[("b", "c")]);
+        let d = diff(&before, &after);
+        let mut buf = Vec::new();
+        write_summary(&d, &mut buf).unwrap();
+        let output = String::from_utf8(buf).unwrap();
+        assert_eq!(
+            output,
+            "\
+added_nodes\t1
+removed_nodes\t1
+changed_nodes\t1
+moved_nodes\t0
+unchanged_nodes\t0
+added_edges\t1
+removed_edges\t1
+changed_edges\t0
+unchanged_edges\t0
+"
+        );
+    }
+
+    #[test]
+    fn summary_all_unchanged() {
+        let g = make_graph(&[("a", "A"), ("b", "B")], &[("a", "b")]);
+        let d = diff(&g, &g);
+        let mut buf = Vec::new();
+        write_summary(&d, &mut buf).unwrap();
+        let output = String::from_utf8(buf).unwrap();
+        assert_eq!(
+            output,
+            "\
+added_nodes\t0
+removed_nodes\t0
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t2
+added_edges\t0
+removed_edges\t0
+changed_edges\t0
+unchanged_edges\t1
+"
+        );
+    }
+}
diff --git a/crates/csvizmo-depgraph/src/algorithm/mod.rs b/crates/csvizmo-depgraph/src/algorithm/mod.rs
index a8e9ebb..c380358 100644
--- a/crates/csvizmo-depgraph/src/algorithm/mod.rs
+++ b/crates/csvizmo-depgraph/src/algorithm/mod.rs
@@ -1,5 +1,6 @@
 pub mod between;
 pub mod cycles;
+pub mod diff;
 pub mod flatten;
 pub mod merge;
 pub mod query;
diff --git a/crates/csvizmo-depgraph/src/bin/graphdiff.rs b/crates/csvizmo-depgraph/src/bin/graphdiff.rs
new file mode 100644
index 0000000..c413e48
--- /dev/null
+++ b/crates/csvizmo-depgraph/src/bin/graphdiff.rs
@@ -0,0 +1,169 @@
+use std::io::{IsTerminal, Read};
+use std::path::{Path, PathBuf};
+
+use clap::{Parser, Subcommand};
+use csvizmo_depgraph::DepGraph;
+use csvizmo_depgraph::algorithm::diff;
+use csvizmo_depgraph::emit::OutputFormat;
+use csvizmo_depgraph::parse::InputFormat;
+use csvizmo_utils::stdio::{get_input_reader, get_output_writer};
+
+/// Compute differences between two dependency graphs.
+///
+/// Takes two graph files (before and after) and produces various
+/// diff representations via subcommands.
+#[derive(Debug, Parser)]
+#[clap(version, verbatim_doc_comment)]
+struct Args {
+    /// Logging level
+    #[clap(long, default_value_t = tracing::Level::INFO)]
+    log_level: tracing::Level,
+
+    /// Input format (auto-detected from extension/content if omitted)
+    #[clap(short = 'I', long, global = true)]
+    input_format: Option<InputFormat>,
+
+    /// Output file (stdout if '-' or omitted)
+    #[clap(short, long, global = true)]
+    output: Option<PathBuf>,
+
+    /// Output format (auto-detected from extension, defaults to DOT)
+    #[clap(short = 'O', long, global = true)]
+    output_format: Option<OutputFormat>,
+
+    /// Exit with code 1 if the graphs differ
+    #[clap(long, global = true)]
+    check: bool,
+
+    #[clap(subcommand)]
+    command: Command,
+}
+
+/// Shared positional arguments for the two input graphs.
+#[derive(Debug, clap::Args)]
+struct Inputs {
+    /// The "before" graph file (use '-' for stdin)
+    before: PathBuf,
+    /// The "after" graph file (use '-' for stdin)
+    after: PathBuf,
+}
+
+#[derive(Debug, Subcommand)]
+enum Command {
+    /// Annotated graph highlighting added/removed/changed/moved nodes and edges
+    Annotate {
+        #[command(flatten)]
+        inputs: Inputs,
+        /// Group added/removed nodes into DOT cluster subgraphs
+        #[clap(long)]
+        cluster: bool,
+    },
+    /// Tab-delimited listing of changed nodes and edges
+    List {
+        #[command(flatten)]
+        inputs: Inputs,
+    },
+    /// Set difference: nodes only in the "before" graph
+    Subtract {
+        #[command(flatten)]
+        inputs: Inputs,
+    },
+    /// Tab-delimited summary counts of changes
+    Summary {
+        #[command(flatten)]
+        inputs: Inputs,
+    },
+}
+
+fn main() -> eyre::Result<()> {
+    let use_color = std::io::stderr().is_terminal();
+    if use_color {
+        color_eyre::install()?;
+    }
+
+    let args = Args::parse();
+
+    let filter = tracing_subscriber::EnvFilter::builder()
+        .with_default_directive(args.log_level.into())
+        .with_env_var("CSV_LOG")
+        .from_env_lossy();
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_ansi(use_color)
+        .with_writer(std::io::stderr)
+        .init();
+
+    let inputs = match &args.command {
+        Command::Annotate { inputs, .. } => inputs,
+        Command::List { inputs } => inputs,
+        Command::Subtract { inputs } => inputs,
+        Command::Summary { inputs } => inputs,
+    };
+
+    let is_stdio = |p: &PathBuf| p.as_os_str() == "-";
+    if is_stdio(&inputs.before) && is_stdio(&inputs.after) {
+        eyre::bail!("at most one input can be '-' (stdin)");
+    }
+
+    let before = read_graph(&inputs.before, args.input_format)?;
+    let after = read_graph(&inputs.after, args.input_format)?;
+
+    tracing::info!(
+        "Before: {} nodes, {} edges; After: {} nodes, {} edges",
+        before.all_nodes().len(),
+        before.all_edges().len(),
+        after.all_nodes().len(),
+        after.all_edges().len()
+    );
+
+    let graph_diff = diff::diff(&before, &after);
+
+    let output_path = args.output.filter(|p| !is_stdio(p));
+    let mut output = get_output_writer(&output_path)?;
+
+    match &args.command {
+        Command::Annotate { cluster, .. } => {
+            let graph = diff::annotate_graph(&graph_diff, &after, *cluster);
+            let output_format = csvizmo_depgraph::emit::resolve_output_format(
+                args.output_format,
+                output_path.as_deref(),
+            )?;
+            csvizmo_depgraph::emit::emit(output_format, &graph, &mut output)?;
+        }
+        Command::List { .. } => {
+            diff::write_list(&graph_diff, &mut output)?;
+        }
+        Command::Subtract { .. } => {
+            let graph = diff::subtract_graph(&graph_diff, &before);
+            let output_format = csvizmo_depgraph::emit::resolve_output_format(
+                args.output_format,
+                output_path.as_deref(),
+            )?;
+            csvizmo_depgraph::emit::emit(output_format, &graph, &mut output)?;
+        }
+        Command::Summary { .. } => {
+            diff::write_summary(&graph_diff, &mut output)?;
+        }
+    }
+
+    if args.check && graph_diff.has_changes() {
+        std::process::exit(1);
+    }
+
+    Ok(())
+}
+
+/// Read and parse a graph from a file path (or stdin if "-").
+fn read_graph(path: &Path, input_format: Option<InputFormat>) -> eyre::Result<DepGraph> {
+    let file_path = if path.as_os_str() == "-" {
+        None
+    } else {
+        Some(path.to_path_buf())
+    };
+    let mut reader = get_input_reader(&file_path)?;
+    let mut text = String::new();
+    reader.read_to_string(&mut text)?;
+    let fmt =
+        csvizmo_depgraph::parse::resolve_input_format(input_format, file_path.as_deref(), &text)?;
+    csvizmo_depgraph::parse::parse(fmt, &text)
+}
diff --git a/crates/csvizmo-depgraph/tests/graphdiff.rs b/crates/csvizmo-depgraph/tests/graphdiff.rs
new file mode 100644
index 0000000..1c45342
--- /dev/null
+++ b/crates/csvizmo-depgraph/tests/graphdiff.rs
@@ -0,0 +1,605 @@
+use csvizmo_test::{CommandExt, tempfile, tool};
+use pretty_assertions::assert_eq;
+
+// -- annotate --
+
+#[test]
+fn annotate_identical_tgf() {
+    let f1 = tempfile("a\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("a\nb\n#\na\tb\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "annotate",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "tgf",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // Unchanged nodes keep their labels, TGF drops diff attrs
+    assert_eq!(stdout, "a\nb\n#\na\tb\n");
+}
+
+#[test]
+fn annotate_added_removed_dot() {
+    let f1 = tempfile("a\n#\n").unwrap();
+    let f2 = tempfile("b\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "annotate",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "dot",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    b [label=\"+ b\", color=\"green\", fontcolor=\"green\", diff=\"added\"];
+    a [label=\"- a\", color=\"red\", fontcolor=\"red\", diff=\"removed\"];
+}
+"
+    );
+}
+
+#[test]
+fn annotate_changed_dot() {
+    let f1 = tempfile("a\tAlpha\n#\n").unwrap();
+    let f2 = tempfile("a\tAleph\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "annotate",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "dot",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    a [label=\"~ Aleph\", color=\"orange\", fontcolor=\"orange\", diff=\"changed\"];
+}
+"
+    );
+}
+
+#[test]
+fn annotate_edge_annotations_dot() {
+    let f1 = tempfile("a\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("a\nc\n#\na\tc\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "annotate",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "dot",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    a [diff=\"unchanged\"];
+    c [label=\"+ c\", color=\"green\", fontcolor=\"green\", diff=\"added\"];
+    b [label=\"- b\", color=\"red\", fontcolor=\"red\", diff=\"removed\"];
+    a -> c [color=\"green\", diff=\"added\"];
+    a -> b [color=\"red\", diff=\"removed\"];
+}
+"
+    );
+}
+
+#[test]
+fn annotate_cluster_dot() {
+    let f1 = tempfile("a\n#\n").unwrap();
+    let f2 = tempfile("b\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "annotate",
+            "--cluster",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "dot",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_removed {
+        a [label=\"- a\", color=\"red\", fontcolor=\"red\", diff=\"removed\"];
+    }
+    b [label=\"+ b\", color=\"green\", fontcolor=\"green\", diff=\"added\"];
+}
+"
+    );
+}
+
+// -- list --
+
+#[test]
+fn list_basic() {
+    let f1 = tempfile("a\tAlpha\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("b\nc\n#\nb\tc\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["list", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // b unchanged (omitted), c added, a removed (with label)
+    // edge b->c added, a->b removed
+    assert_eq!(stdout, "+\tc\n-\ta\tAlpha\n+\tb\tc\n-\ta\tb\n");
+}
+
+#[test]
+fn list_empty_diff() {
+    let f1 = tempfile("a\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("a\nb\n#\na\tb\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["list", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "");
+}
+
+// -- subtract --
+
+#[test]
+fn subtract_basic() {
+    let f1 = tempfile("a\nb\nc\n#\na\tb\nb\tc\n").unwrap();
+    let f2 = tempfile("c\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "subtract",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "tgf",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // Only a and b are removed; edge a->b has both endpoints removed
+    // Edge b->c is excluded because c is not removed
+    assert_eq!(stdout, "a\nb\n#\na\tb\n");
+}
+
+#[test]
+fn subtract_empty_when_identical() {
+    let f1 = tempfile("a\n#\n").unwrap();
+    let f2 = tempfile("a\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "subtract",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "tgf",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "#\n");
+}
+
+// -- summary --
+
+#[test]
+fn summary_basic() {
+    let f1 = tempfile("a\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("b\nc\n#\nb\tc\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t1
+removed_nodes\t1
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t1
+added_edges\t1
+removed_edges\t1
+changed_edges\t0
+unchanged_edges\t0
+"
+    );
+}
+
+#[test]
+fn summary_all_unchanged() {
+    let f1 = tempfile("a\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("a\nb\n#\na\tb\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t0
+removed_nodes\t0
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t2
+added_edges\t0
+removed_edges\t0
+changed_edges\t0
+unchanged_edges\t1
+"
+    );
+}
+
+#[test]
+fn summary_all_different() {
+    let f1 = tempfile("a\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("c\nd\n#\nc\td\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t2
+removed_nodes\t2
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t0
+added_edges\t1
+removed_edges\t1
+changed_edges\t0
+unchanged_edges\t0
+"
+    );
+}
+
+#[test]
+fn summary_empty_graphs() {
+    let f1 = tempfile("#\n").unwrap();
+    let f2 = tempfile("#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t0
+removed_nodes\t0
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t0
+added_edges\t0
+removed_edges\t0
+changed_edges\t0
+unchanged_edges\t0
+"
+    );
+}
+
+// -- input handling --
+
+#[test]
+fn stdin_and_file() {
+    let f1 = tempfile("a\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg("-")
+        .write_stdin("b\n#\n")
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t1
+removed_nodes\t1
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t0
+added_edges\t0
+removed_edges\t0
+changed_edges\t0
+unchanged_edges\t0
+"
+    );
+}
+
+#[test]
+fn both_stdin_error() {
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf", "-", "-"])
+        .write_stdin("")
+        .captured_output()
+        .unwrap();
+    assert!(!output.status.success());
+}
+
+// -- check flag --
+
+#[test]
+fn check_identical_exits_zero() {
+    let f1 = tempfile("a\nb\n#\na\tb\n").unwrap();
+    let f2 = tempfile("a\nb\n#\na\tb\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--check", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+}
+
+#[test]
+fn check_different_exits_nonzero() {
+    let f1 = tempfile("a\n#\n").unwrap();
+    let f2 = tempfile("b\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--check", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(!output.status.success());
+}
+
+#[test]
+fn check_still_produces_output() {
+    let f1 = tempfile("a\n#\n").unwrap();
+    let f2 = tempfile("b\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["list", "--check", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(!output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "+\tb\n-\ta\n");
+}
+
+// -- moved --
+
+#[test]
+fn moved_node_list() {
+    // c has same info but different single parent
+    let f1 = tempfile("p1\nc\n#\np1\tc\n").unwrap();
+    let f2 = tempfile("p2\nc\n#\np2\tc\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["list", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // p2 added, c moved, p1 removed; edges follow
+    assert_eq!(stdout, "+\tp2\n>\tc\n-\tp1\n+\tp2\tc\n-\tp1\tc\n");
+}
+
+#[test]
+fn moved_node_annotate_dot() {
+    let f1 = tempfile("p1\nc\n#\np1\tc\n").unwrap();
+    let f2 = tempfile("p2\nc\n#\np2\tc\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args([
+            "annotate",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "dot",
+        ])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    p2 [label=\"+ p2\", color=\"green\", fontcolor=\"green\", diff=\"added\"];
+    c [label=\"> c\", color=\"blue\", fontcolor=\"blue\", diff=\"moved\"];
+    p1 [label=\"- p1\", color=\"red\", fontcolor=\"red\", diff=\"removed\"];
+    p2 -> c [color=\"green\", diff=\"added\"];
+    p1 -> c [color=\"red\", diff=\"removed\"];
+}
+"
+    );
+}
+
+#[test]
+fn multi_parent_not_moved() {
+    // c has multiple parents in both graphs -- not moved
+    let f1 = tempfile("p1\np2\nc\n#\np1\tc\np2\tc\n").unwrap();
+    let f2 = tempfile("p1\np3\nc\n#\np1\tc\np3\tc\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // c is unchanged (not moved), p1 unchanged, p3 added, p2 removed
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t1
+removed_nodes\t1
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t2
+added_edges\t1
+removed_edges\t1
+changed_edges\t0
+unchanged_edges\t1
+"
+    );
+}
+
+// -- edge cases --
+
+#[test]
+fn changed_edges() {
+    // Same edge (a->b) but different label
+    let f1 = tempfile("a\nb\n#\na\tb\tuses\n").unwrap();
+    let f2 = tempfile("a\nb\n#\na\tb\tdepends\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t0
+removed_nodes\t0
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t2
+added_edges\t0
+removed_edges\t0
+changed_edges\t1
+unchanged_edges\t0
+"
+    );
+}
+
+#[test]
+fn duplicate_edges() {
+    // Two edges a->b with different labels in each graph
+    // "uses" is in both (unchanged), "dev" only in before (removed), "test" only in after (added)
+    let f1 = tempfile("a\nb\n#\na\tb\tuses\na\tb\tdev\n").unwrap();
+    let f2 = tempfile("a\nb\n#\na\tb\tuses\na\tb\ttest\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["summary", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // "uses" matched unchanged, "test" paired with "dev" as changed
+    assert_eq!(
+        stdout,
+        "\
+added_nodes\t0
+removed_nodes\t0
+changed_nodes\t0
+moved_nodes\t0
+unchanged_nodes\t2
+added_edges\t0
+removed_edges\t0
+changed_edges\t1
+unchanged_edges\t1
+"
+    );
+}
+
+#[test]
+fn nodes_only_graphs() {
+    let f1 = tempfile("a\nb\n#\n").unwrap();
+    let f2 = tempfile("b\nc\n#\n").unwrap();
+
+    let output = tool!("graphdiff")
+        .args(["list", "--input-format", "tgf"])
+        .arg(f1.path())
+        .arg(f2.path())
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "+\tc\n-\ta\n");
+}

From 9f4a2547d286a42537e05bf8a4716194199f233d Mon Sep 17 00:00:00 2001
From: Austin Gill <Notgnoshi@gmail.com>
Date: Sat, 21 Feb 2026 10:11:33 -0600
Subject: [PATCH 3/6] Add depcluster tool

---
 Cargo.toml                                    |   2 +
 crates/csvizmo-depgraph/Cargo.toml            |   2 +
 .../src/algorithm/cluster/graphrs_bridge.rs   |  89 ++++++
 .../src/algorithm/cluster/lpa.rs              | 161 ++++++++++
 .../src/algorithm/cluster/mod.rs              | 189 ++++++++++++
 crates/csvizmo-depgraph/src/algorithm/mod.rs  |   1 +
 crates/csvizmo-depgraph/src/bin/depcluster.rs | 133 +++++++++
 crates/csvizmo-depgraph/tests/depcluster.rs   | 276 ++++++++++++++++++
 8 files changed, 853 insertions(+)
 create mode 100644 crates/csvizmo-depgraph/src/algorithm/cluster/graphrs_bridge.rs
 create mode 100644 crates/csvizmo-depgraph/src/algorithm/cluster/lpa.rs
 create mode 100644 crates/csvizmo-depgraph/src/algorithm/cluster/mod.rs
 create mode 100644 crates/csvizmo-depgraph/src/bin/depcluster.rs
 create mode 100644 crates/csvizmo-depgraph/tests/depcluster.rs

diff --git a/Cargo.toml b/Cargo.toml
index 8c43aa9..b4a43e4 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -28,6 +28,7 @@ either = "1"
 eyre = "0.6.12"
 globset = "0.4.18"
 gnuplot = "0.0.46"
+graphrs = "0.11"
 hex = { version = "0.4.3", features = ["serde"] }
 indexmap = "2"
 itertools = "0.14.0"
@@ -36,6 +37,7 @@ itertools-num = "0.1.3"
 kernel-density-estimation = "0.2.0"
 ordered-float = "5.0.0"
 petgraph = "0.8"
+rand = "0.9"
 regex = "1"
 pathdiff = "0.2.3"
 serde = { version = "1.0.217", features = ["derive"] }
diff --git a/crates/csvizmo-depgraph/Cargo.toml b/crates/csvizmo-depgraph/Cargo.toml
index 7d9015a..055e25e 100644
--- a/crates/csvizmo-depgraph/Cargo.toml
+++ b/crates/csvizmo-depgraph/Cargo.toml
@@ -17,9 +17,11 @@ dot-parser = { workspace = true, optional = true }
 either = { workspace = true, optional = true }
 eyre.workspace = true
 globset.workspace = true
+graphrs.workspace = true
 indexmap.workspace = true
 csvizmo-minpath.workspace = true
 petgraph.workspace = true
+rand.workspace = true
 regex.workspace = true
 mermaid-rs-renderer.workspace = true
 serde.workspace = true
diff --git a/crates/csvizmo-depgraph/src/algorithm/cluster/graphrs_bridge.rs b/crates/csvizmo-depgraph/src/algorithm/cluster/graphrs_bridge.rs
new file mode 100644
index 0000000..7ac6742
--- /dev/null
+++ b/crates/csvizmo-depgraph/src/algorithm/cluster/graphrs_bridge.rs
@@ -0,0 +1,89 @@
+use std::collections::HashSet;
+
+use graphrs::algorithms::community::{leiden, louvain};
+use graphrs::{Edge, Graph, GraphSpecs, Node};
+
+use super::clusters_to_depgraph;
+use crate::DepGraph;
+
+/// Convert a DepGraph into a graphrs Graph.
+fn depgraph_to_graphrs(graph: &DepGraph, directed: bool) -> eyre::Result<Graph<String, ()>> {
+    let specs = if directed {
+        GraphSpecs::directed_create_missing()
+    } else {
+        GraphSpecs::undirected_create_missing()
+    };
+
+    let all_nodes = graph.all_nodes();
+    let all_edges = graph.all_edges();
+
+    let nodes: Vec<_> = all_nodes
+        .keys()
+        .map(|id| Node::from_name(id.clone()))
+        .collect();
+
+    let edges: Vec<_> = all_edges
+        .iter()
+        .map(|e| Edge::new(e.from.clone(), e.to.clone()))
+        .collect();
+
+    let g = Graph::new_from_nodes_and_edges(nodes, edges, specs)
+        .map_err(|e| eyre::eyre!("graphrs error: {e}"))?;
+
+    Ok(g)
+}
+
+/// Convert graphrs community result (`Vec<HashSet<String>>`) to our partition format.
+fn communities_to_partition(graph: &DepGraph, communities: Vec<HashSet<String>>) -> Vec<Vec<&str>> {
+    let all_nodes = graph.all_nodes();
+    communities
+        .iter()
+        .map(|community| {
+            let mut ids: Vec<&str> = all_nodes
+                .keys()
+                .filter(|id| community.contains(id.as_str()))
+                .map(|id| id.as_str())
+                .collect();
+            ids.sort();
+            ids
+        })
+        .collect()
+}
+
+/// Run the Louvain community detection algorithm on the dependency graph.
+pub fn louvain_clustering(
+    graph: &DepGraph,
+    directed: bool,
+    resolution: f64,
+    seed: Option<u64>,
+) -> eyre::Result<DepGraph> {
+    let g = depgraph_to_graphrs(graph, directed)?;
+
+    let communities = louvain::louvain_communities(&g, false, Some(resolution), None, seed)
+        .map_err(|e| eyre::eyre!("louvain error: {e}"))?;
+
+    let partition = communities_to_partition(graph, communities);
+    Ok(clusters_to_depgraph(graph, &partition))
+}
+
+/// Run the Leiden community detection algorithm on the dependency graph.
+pub fn leiden_clustering(
+    graph: &DepGraph,
+    directed: bool,
+    resolution: f64,
+) -> eyre::Result<DepGraph> {
+    let g = depgraph_to_graphrs(graph, directed)?;
+
+    let communities = leiden::leiden(
+        &g,
+        false,
+        leiden::QualityFunction::CPM,
+        Some(resolution),
+        None,
+        None,
+    )
+    .map_err(|e| eyre::eyre!("leiden error: {e}"))?;
+
+    let partition = communities_to_partition(graph, communities);
+    Ok(clusters_to_depgraph(graph, &partition))
+}
diff --git a/crates/csvizmo-depgraph/src/algorithm/cluster/lpa.rs b/crates/csvizmo-depgraph/src/algorithm/cluster/lpa.rs
new file mode 100644
index 0000000..c949660
--- /dev/null
+++ b/crates/csvizmo-depgraph/src/algorithm/cluster/lpa.rs
@@ -0,0 +1,161 @@
+use std::collections::HashMap;
+
+use rand::SeedableRng;
+use rand::prelude::SliceRandom;
+use rand::rngs::StdRng;
+
+use super::{Adjacency, clusters_to_depgraph};
+use crate::{DepGraph, FlatGraphView};
+
+/// Run Label Propagation Algorithm on the dependency graph.
+///
+/// Each node starts in its own cluster. Each iteration, nodes adopt the most common
+/// cluster label among their neighbors (ties broken by smallest label). Stops when
+/// no labels change or `max_iter` is reached.
+///
+/// If `seed` is provided, the node processing order is shuffled each iteration.
+/// Otherwise, nodes are processed in graph order (deterministic).
+pub fn lpa(graph: &DepGraph, directed: bool, max_iter: usize, seed: Option<u64>) -> DepGraph {
+    let view = FlatGraphView::new(graph);
+    let n = view.idx_to_id.len();
+
+    if n == 0 {
+        return DepGraph::default();
+    }
+
+    let adj = Adjacency::new(&view, directed);
+
+    // Each node starts with its own label (index).
+    let mut labels: Vec<usize> = (0..n).collect();
+
+    let mut rng = seed.map(StdRng::seed_from_u64);
+    let mut order: Vec<usize> = (0..n).collect();
+
+    for _ in 0..max_iter {
+        if let Some(rng) = rng.as_mut() {
+            order.shuffle(rng);
+        }
+
+        let mut changed = false;
+        for &i in &order {
+            let neighbors = &adj.neighbors[i];
+            if neighbors.is_empty() {
+                continue;
+            }
+
+            // Count neighbor labels.
+            let mut counts: HashMap<usize, usize> = HashMap::new();
+            for &neighbor in neighbors {
+                *counts.entry(labels[neighbor]).or_default() += 1;
+            }
+
+            // Find most common label; ties broken by smallest label.
+            let mut best_label = labels[i];
+            let mut best_count = 0;
+            for (&label, &count) in &counts {
+                if count > best_count || (count == best_count && label < best_label) {
+                    best_label = label;
+                    best_count = count;
+                }
+            }
+
+            if best_label != labels[i] {
+                labels[i] = best_label;
+                changed = true;
+            }
+        }
+
+        if !changed {
+            break;
+        }
+    }
+
+    // Convert label assignments to partition.
+    let mut cluster_map: HashMap<usize, Vec<&str>> = HashMap::new();
+    for (i, &label) in labels.iter().enumerate() {
+        cluster_map
+            .entry(label)
+            .or_default()
+            .push(view.idx_to_id[i]);
+    }
+
+    // Sort clusters by their smallest label for deterministic output.
+    let mut clusters: Vec<(usize, Vec<&str>)> = cluster_map.into_iter().collect();
+    clusters.sort_by_key(|(label, _)| *label);
+    let partition: Vec<Vec<&str>> = clusters.into_iter().map(|(_, ids)| ids).collect();
+
+    clusters_to_depgraph(graph, &partition)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{Edge, NodeInfo};
+
+    fn make_graph(nodes: &[(&str, &str)], edges: &[(&str, &str)]) -> DepGraph {
+        DepGraph {
+            nodes: nodes
+                .iter()
+                .map(|(id, label)| (id.to_string(), NodeInfo::new(*label)))
+                .collect(),
+            edges: edges
+                .iter()
+                .map(|(from, to)| Edge {
+                    from: from.to_string(),
+                    to: to.to_string(),
+                    ..Default::default()
+                })
+                .collect(),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn two_disconnected_components() {
+        let g = make_graph(
+            &[("a", "a"), ("b", "b"), ("c", "c"), ("d", "d")],
+            &[("a", "b"), ("c", "d")],
+        );
+        let result = lpa(&g, false, 100, None);
+        assert_eq!(result.subgraphs.len(), 2);
+        // No cross-cluster edges
+        assert!(result.edges.is_empty());
+    }
+
+    #[test]
+    fn single_clique() {
+        // Fully connected: a-b, b-c, a-c -- should all be in one cluster
+        let g = make_graph(
+            &[("a", "a"), ("b", "b"), ("c", "c")],
+            &[
+                ("a", "b"),
+                ("b", "c"),
+                ("a", "c"),
+                ("b", "a"),
+                ("c", "b"),
+                ("c", "a"),
+            ],
+        );
+        let result = lpa(&g, false, 100, None);
+        assert_eq!(result.subgraphs.len(), 1);
+        assert_eq!(result.subgraphs[0].nodes.len(), 3);
+    }
+
+    #[test]
+    fn empty_graph() {
+        let g = DepGraph::default();
+        let result = lpa(&g, false, 100, None);
+        assert!(result.subgraphs.is_empty());
+        assert!(result.edges.is_empty());
+    }
+
+    #[test]
+    fn with_seed() {
+        let g = make_graph(
+            &[("a", "a"), ("b", "b"), ("c", "c"), ("d", "d")],
+            &[("a", "b"), ("c", "d")],
+        );
+        let result = lpa(&g, false, 100, Some(42));
+        assert_eq!(result.subgraphs.len(), 2);
+    }
+}
diff --git a/crates/csvizmo-depgraph/src/algorithm/cluster/mod.rs b/crates/csvizmo-depgraph/src/algorithm/cluster/mod.rs
new file mode 100644
index 0000000..93d2dd2
--- /dev/null
+++ b/crates/csvizmo-depgraph/src/algorithm/cluster/mod.rs
@@ -0,0 +1,189 @@
+pub mod graphrs_bridge;
+pub mod lpa;
+
+use std::collections::HashMap;
+
+use indexmap::IndexMap;
+use petgraph::Direction;
+
+use crate::{DepGraph, Edge, FlatGraphView, NodeInfo};
+
+/// Precomputed neighbor lists from a flattened dependency graph.
+///
+/// In undirected mode, neighbors include both incoming and outgoing edges (deduplicated).
+/// In directed mode, only outgoing neighbors are included.
+pub struct Adjacency {
+    /// For each node index, the set of neighbor node indices.
+    pub neighbors: Vec<Vec<usize>>,
+}
+
+impl Adjacency {
+    pub fn new(view: &FlatGraphView, directed: bool) -> Self {
+        let n = view.idx_to_id.len();
+        let mut neighbors = vec![Vec::new(); n];
+
+        for idx in view.pg.node_indices() {
+            let i = idx.index();
+            let mut seen = Vec::new();
+
+            for neighbor in view.pg.neighbors_directed(idx, Direction::Outgoing) {
+                seen.push(neighbor.index());
+            }
+
+            if !directed {
+                for neighbor in view.pg.neighbors_directed(idx, Direction::Incoming) {
+                    if !seen.contains(&neighbor.index()) {
+                        seen.push(neighbor.index());
+                    }
+                }
+            }
+
+            neighbors[i] = seen;
+        }
+
+        Adjacency { neighbors }
+    }
+}
+
+/// Convert a partition (list of clusters, each a list of node IDs) into a DepGraph with
+/// one subgraph per cluster. Intra-cluster edges go in the subgraph; cross-cluster edges
+/// go at the top level.
+pub fn clusters_to_depgraph(graph: &DepGraph, partition: &[Vec<&str>]) -> DepGraph {
+    let all_nodes = graph.all_nodes();
+    let all_edges = graph.all_edges();
+
+    // Map each node ID to its cluster index.
+    let mut node_to_cluster: HashMap<&str, usize> = HashMap::new();
+    for (i, cluster) in partition.iter().enumerate() {
+        for &id in cluster {
+            node_to_cluster.insert(id, i);
+        }
+    }
+
+    let mut subgraphs = Vec::new();
+    for (i, cluster) in partition.iter().enumerate() {
+        let cluster_ids: std::collections::HashSet<&str> = cluster.iter().copied().collect();
+
+        let nodes: IndexMap<String, NodeInfo> = all_nodes
+            .iter()
+            .filter(|(id, _)| cluster_ids.contains(id.as_str()))
+            .map(|(id, info)| (id.clone(), info.clone()))
+            .collect();
+
+        let edges: Vec<Edge> = all_edges
+            .iter()
+            .filter(|e| {
+                cluster_ids.contains(e.from.as_str()) && cluster_ids.contains(e.to.as_str())
+            })
+            .cloned()
+            .collect();
+
+        subgraphs.push(DepGraph {
+            id: Some(format!("cluster_{i}")),
+            nodes,
+            edges,
+            ..Default::default()
+        });
+    }
+
+    // Cross-cluster edges: both endpoints assigned to clusters but in different ones.
+    let cross_edges: Vec<Edge> = all_edges
+        .iter()
+        .filter(|e| {
+            match (
+                node_to_cluster.get(e.from.as_str()),
+                node_to_cluster.get(e.to.as_str()),
+            ) {
+                (Some(cf), Some(ct)) => cf != ct,
+                _ => false,
+            }
+        })
+        .cloned()
+        .collect();
+
+    DepGraph {
+        edges: cross_edges,
+        subgraphs,
+        ..Default::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_graph(nodes: &[(&str, &str)], edges: &[(&str, &str)]) -> DepGraph {
+        DepGraph {
+            nodes: nodes
+                .iter()
+                .map(|(id, label)| (id.to_string(), NodeInfo::new(*label)))
+                .collect(),
+            edges: edges
+                .iter()
+                .map(|(from, to)| Edge {
+                    from: from.to_string(),
+                    to: to.to_string(),
+                    ..Default::default()
+                })
+                .collect(),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn adjacency_undirected() {
+        let g = make_graph(&[("a", "a"), ("b", "b"), ("c", "c")], &[("a", "b")]);
+        let view = FlatGraphView::new(&g);
+        let adj = Adjacency::new(&view, false);
+        // a's neighbors: b (outgoing) -> [b_idx]
+        let a_idx = view.id_to_idx["a"].index();
+        let b_idx = view.id_to_idx["b"].index();
+        assert!(adj.neighbors[a_idx].contains(&b_idx));
+        // b's neighbors: a (incoming, undirected) -> [a_idx]
+        assert!(adj.neighbors[b_idx].contains(&a_idx));
+    }
+
+    #[test]
+    fn adjacency_directed() {
+        let g = make_graph(&[("a", "a"), ("b", "b")], &[("a", "b")]);
+        let view = FlatGraphView::new(&g);
+        let adj = Adjacency::new(&view, true);
+        let a_idx = view.id_to_idx["a"].index();
+        let b_idx = view.id_to_idx["b"].index();
+        // a -> b: a has neighbor b
+        assert!(adj.neighbors[a_idx].contains(&b_idx));
+        // b has no outgoing edges in directed mode
+        assert!(adj.neighbors[b_idx].is_empty());
+    }
+
+    #[test]
+    fn clusters_to_depgraph_basic() {
+        let g = make_graph(
+            &[("a", "a"), ("b", "b"), ("c", "c"), ("d", "d")],
+            &[("a", "b"), ("c", "d"), ("b", "c")],
+        );
+        let partition = vec![vec!["a", "b"], vec!["c", "d"]];
+        let result = clusters_to_depgraph(&g, &partition);
+
+        assert_eq!(result.subgraphs.len(), 2);
+        assert_eq!(result.subgraphs[0].id.as_deref(), Some("cluster_0"));
+        assert_eq!(result.subgraphs[0].nodes.len(), 2);
+        assert_eq!(result.subgraphs[0].edges.len(), 1); // a->b
+        assert_eq!(result.subgraphs[1].id.as_deref(), Some("cluster_1"));
+        assert_eq!(result.subgraphs[1].nodes.len(), 2);
+        assert_eq!(result.subgraphs[1].edges.len(), 1); // c->d
+        // Cross-cluster edge: b->c
+        assert_eq!(result.edges.len(), 1);
+        assert_eq!(result.edges[0].from, "b");
+        assert_eq!(result.edges[0].to, "c");
+    }
+
+    #[test]
+    fn clusters_to_depgraph_empty() {
+        let g = DepGraph::default();
+        let partition: Vec<Vec<&str>> = vec![];
+        let result = clusters_to_depgraph(&g, &partition);
+        assert!(result.subgraphs.is_empty());
+        assert!(result.edges.is_empty());
+    }
+}
diff --git a/crates/csvizmo-depgraph/src/algorithm/mod.rs b/crates/csvizmo-depgraph/src/algorithm/mod.rs
index c380358..7cf9471 100644
--- a/crates/csvizmo-depgraph/src/algorithm/mod.rs
+++ b/crates/csvizmo-depgraph/src/algorithm/mod.rs
@@ -1,4 +1,5 @@
 pub mod between;
+pub mod cluster;
 pub mod cycles;
 pub mod diff;
 pub mod flatten;
diff --git a/crates/csvizmo-depgraph/src/bin/depcluster.rs b/crates/csvizmo-depgraph/src/bin/depcluster.rs
new file mode 100644
index 0000000..983ad16
--- /dev/null
+++ b/crates/csvizmo-depgraph/src/bin/depcluster.rs
@@ -0,0 +1,133 @@
+use std::io::{IsTerminal, Read};
+use std::path::PathBuf;
+
+use clap::Parser;
+use csvizmo_depgraph::algorithm::cluster::{graphrs_bridge, lpa};
+use csvizmo_depgraph::emit::OutputFormat;
+use csvizmo_depgraph::parse::InputFormat;
+use csvizmo_utils::stdio::{get_input_reader, get_output_writer};
+
+/// Cluster nodes in a dependency graph using community detection algorithms.
+///
+/// Runs a community detection algorithm on the input graph and outputs the result
+/// with one subgraph per cluster. Cross-cluster edges appear at the top level.
+#[derive(Debug, Parser)]
+#[clap(version, verbatim_doc_comment)]
+struct Args {
+    /// Logging level
+    #[clap(long, default_value_t = tracing::Level::INFO)]
+    log_level: tracing::Level,
+
+    /// Input file (stdin if '-' or omitted)
+    #[clap(short, long)]
+    input: Option<PathBuf>,
+
+    /// Input format (auto-detected from extension/content if omitted)
+    #[clap(short = 'I', long)]
+    input_format: Option<InputFormat>,
+
+    /// Output file (stdout if '-' or omitted)
+    #[clap(short, long)]
+    output: Option<PathBuf>,
+
+    /// Output format (auto-detected from extension, defaults to DOT)
+    #[clap(short = 'O', long)]
+    output_format: Option<OutputFormat>,
+
+    /// Clustering algorithm
+    #[clap(short, long, default_value_t, value_enum)]
+    algorithm: Algorithm,
+
+    /// Use directed edges only (default: undirected/bidirectional)
+    #[clap(long)]
+    directed: bool,
+
+    /// Maximum iterations (LPA only)
+    #[clap(long, default_value_t = 100)]
+    max_iter: usize,
+
+    /// Random seed (LPA: shuffle order; Louvain: reproducibility)
+    #[clap(long)]
+    seed: Option<u64>,
+
+    /// Resolution parameter; higher = more clusters (Louvain/Leiden only)
+    #[clap(long, default_value_t = 1.0)]
+    resolution: f64,
+}
+
+#[derive(Clone, Copy, Debug, Default, clap::ValueEnum)]
+enum Algorithm {
+    Lpa,
+    #[default]
+    Louvain,
+    Leiden,
+}
+
+impl std::fmt::Display for Algorithm {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Algorithm::Lpa => write!(f, "lpa"),
+            Algorithm::Louvain => write!(f, "louvain"),
+            Algorithm::Leiden => write!(f, "leiden"),
+        }
+    }
+}
+
+fn main() -> eyre::Result<()> {
+    let use_color = std::io::stderr().is_terminal();
+    if use_color {
+        color_eyre::install()?;
+    }
+
+    let args = Args::parse();
+
+    let filter = tracing_subscriber::EnvFilter::builder()
+        .with_default_directive(args.log_level.into())
+        .with_env_var("CSV_LOG")
+        .from_env_lossy();
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_ansi(use_color)
+        .with_writer(std::io::stderr)
+        .init();
+
+    // Normalize `-` to None -- it means stdio, not a file path.
+    let is_stdio = |p: &PathBuf| p.as_os_str() == "-";
+    let input_path = args.input.filter(|p| !is_stdio(p));
+    let output_path = args.output.filter(|p| !is_stdio(p));
+
+    let mut input = get_input_reader(&input_path)?;
+    let mut input_text = String::new();
+    input.read_to_string(&mut input_text)?;
+
+    let input_format = csvizmo_depgraph::parse::resolve_input_format(
+        args.input_format,
+        input_path.as_deref(),
+        &input_text,
+    )?;
+    let output_format =
+        csvizmo_depgraph::emit::resolve_output_format(args.output_format, output_path.as_deref())?;
+
+    let graph = csvizmo_depgraph::parse::parse(input_format, &input_text)?;
+    tracing::info!(
+        "Parsed graph with {} nodes, {} edges, and {} subgraphs",
+        graph.all_nodes().len(),
+        graph.all_edges().len(),
+        graph.subgraphs.len()
+    );
+
+    let graph = match args.algorithm {
+        Algorithm::Lpa => lpa::lpa(&graph, args.directed, args.max_iter, args.seed),
+        Algorithm::Louvain => {
+            graphrs_bridge::louvain_clustering(&graph, args.directed, args.resolution, args.seed)?
+        }
+        Algorithm::Leiden => {
+            graphrs_bridge::leiden_clustering(&graph, args.directed, args.resolution)?
+        }
+    };
+
+    let mut output = get_output_writer(&output_path)?;
+    csvizmo_depgraph::emit::emit(output_format, &graph, &mut output)?;
+
+    Ok(())
+}
diff --git a/crates/csvizmo-depgraph/tests/depcluster.rs b/crates/csvizmo-depgraph/tests/depcluster.rs
new file mode 100644
index 0000000..d7bc4c0
--- /dev/null
+++ b/crates/csvizmo-depgraph/tests/depcluster.rs
@@ -0,0 +1,276 @@
+use csvizmo_test::{CommandExt, tool};
+use pretty_assertions::assert_eq;
+
+/// Two disconnected components: a-b and c-d.
+const TWO_COMPONENTS: &str = "1\ta\n2\tb\n3\tc\n4\td\n#\n1\t2\n3\t4\n";
+
+/// Single clique: a -> b -> c -> a (all connected).
+const SINGLE_CLIQUE: &str = "1\ta\n2\tb\n3\tc\n#\n1\t2\n2\t3\n3\t1\n";
+
+// -- LPA tests (deterministic without seed) --
+
+#[test]
+fn lpa_two_disconnected_components() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "lpa"])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_0 {
+        \"1\" [label=\"a\"];
+        \"2\" [label=\"b\"];
+        \"1\" -> \"2\";
+    }
+    subgraph cluster_1 {
+        \"3\" [label=\"c\"];
+        \"4\" [label=\"d\"];
+        \"3\" -> \"4\";
+    }
+}
+"
+    );
+}
+
+#[test]
+fn lpa_single_clique() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "lpa"])
+        .write_stdin(SINGLE_CLIQUE)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_0 {
+        \"1\" [label=\"a\"];
+        \"2\" [label=\"b\"];
+        \"3\" [label=\"c\"];
+        \"1\" -> \"2\";
+        \"2\" -> \"3\";
+        \"3\" -> \"1\";
+    }
+}
+"
+    );
+}
+
+#[test]
+fn lpa_empty_graph() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "lpa"])
+        .write_stdin("")
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "digraph {\n}\n");
+}
+
+#[test]
+fn lpa_directed_flag() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "lpa", "--directed"])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // With --directed, should still find two components (no cross edges)
+    assert!(stdout.contains("cluster_0"));
+    assert!(stdout.contains("cluster_1"));
+}
+
+#[test]
+fn lpa_seed_flag() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "lpa", "--seed", "42"])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // Two disconnected components should still produce two clusters
+    assert!(stdout.contains("cluster_0"));
+    assert!(stdout.contains("cluster_1"));
+}
+
+#[test]
+fn lpa_max_iter_flag() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "lpa", "--max-iter", "1"])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+}
+
+// -- Louvain tests --
+
+#[test]
+fn louvain_two_disconnected_components() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "louvain"])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // Should produce two clusters with all four nodes and no cross edges
+    assert!(stdout.contains("cluster_0"));
+    assert!(stdout.contains("cluster_1"));
+    assert!(!stdout.contains("cluster_2"));
+    for node in &["\"1\"", "\"2\"", "\"3\"", "\"4\""] {
+        assert!(stdout.contains(node), "missing node {node}");
+    }
+}
+
+#[test]
+fn louvain_resolution_flag() {
+    let output = tool!("depcluster")
+        .args([
+            "--input-format",
+            "tgf",
+            "-a",
+            "louvain",
+            "--resolution",
+            "0.5",
+        ])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+}
+
+#[test]
+fn louvain_seed_flag() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "louvain", "--seed", "123"])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+}
+
+#[test]
+fn louvain_empty_graph() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "louvain"])
+        .write_stdin("")
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "digraph {\n}\n");
+}
+
+// -- Leiden tests --
+
+#[test]
+fn leiden_accepts_input() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "leiden"])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // All nodes should appear somewhere in the output
+    for node in &["\"1\"", "\"2\"", "\"3\"", "\"4\""] {
+        assert!(stdout.contains(node), "missing node {node}");
+    }
+}
+
+#[test]
+fn leiden_resolution_flag() {
+    let output = tool!("depcluster")
+        .args([
+            "--input-format",
+            "tgf",
+            "-a",
+            "leiden",
+            "--resolution",
+            "0.1",
+        ])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+}
+
+#[test]
+fn leiden_empty_graph() {
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "leiden"])
+        .write_stdin("")
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "digraph {\n}\n");
+}
+
+// -- Cross-algorithm tests --
+
+#[test]
+fn cross_cluster_edges_at_top_level() {
+    // Two cliques connected by one directed edge: a<->b connected to c<->d via b->c.
+    // In directed mode, each node only has 1 outgoing neighbor within its pair,
+    // so the single cross-edge b->c doesn't merge the clusters.
+    let input = "1\ta\n2\tb\n3\tc\n4\td\n#\n1\t2\n2\t1\n3\t4\n4\t3\n2\t3\n";
+    let output = tool!("depcluster")
+        .args(["--input-format", "tgf", "-a", "lpa", "--directed"])
+        .write_stdin(input)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_0 {
+        \"1\" [label=\"a\"];
+        \"2\" [label=\"b\"];
+        \"1\" -> \"2\";
+        \"2\" -> \"1\";
+    }
+    subgraph cluster_1 {
+        \"3\" [label=\"c\"];
+        \"4\" [label=\"d\"];
+        \"3\" -> \"4\";
+        \"4\" -> \"3\";
+    }
+    \"2\" -> \"3\";
+}
+"
+    );
+}
+
+#[test]
+fn output_format_tgf() {
+    let output = tool!("depcluster")
+        .args([
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "tgf",
+            "-a",
+            "lpa",
+        ])
+        .write_stdin(TWO_COMPONENTS)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    // TGF doesn't support subgraphs, but the output should still be valid
+    assert!(stdout.contains("#"));
+}

From a5ae8085509b50623c6048e68bdf639a9267364e Mon Sep 17 00:00:00 2001
From: Austin Gill <Notgnoshi@gmail.com>
Date: Sat, 21 Feb 2026 10:49:09 -0600
Subject: [PATCH 4/6] Add depcluster and graphdiff blurbs to README

---
 README.md | 91 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 70 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 60efbc1..85f5af1 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ Gizmos for working with CSVs
 * [canstruct](#canstruct) -- reconstruct NMEA 2000 Fast Packet / ISO 11783-3 Transport Protocol
   sessions
 * [depquery](#depquery) -- query properties of dependency graphs
+* [depcluster](#depcluster) -- cluster dependency graphs using community detection
+* [graphdiff](#graphdiff) -- compare two dependency graphs
 * [bbclasses](#bbclasses) -- generate BitBake recipe inheritance diagrams
 
 # Philosophy
@@ -251,13 +253,6 @@ Converting from a rich format (DOT, cargo metadata) to a simpler one (TGF, depfi
 unsupported attributes. Converting in the other direction preserves graph topology but cannot
 recover lost metadata.
 
-> [!NOTE]
->
-> DOT parsing requires building with `--features dot`, which pulls in the `dot-parser` crate
-> (GPL-2.0). The default build does not include this feature and is MIT-licensed. When built with
-> `--features dot`, the resulting binary is GPL-2.0. DOT _emitting_ is always available (custom
-> string formatting, no GPL dependency).
-
 ## depfilter
 
 Filter or select subsets of dependency graphs. Works on the same formats as `depconv`, and is
@@ -282,11 +277,6 @@ digraph {
 }
 ```
 
-> [!NOTE]
->
-> The `depfilter` tool shares the same GPL-2.0 license caveat as `depconv` with respect to DOT
-> parsing.
-
 ## deptransform
 
 Structural transformations on dependency graphs. Works on the same formats as `depconv`, and is
@@ -309,11 +299,6 @@ $ cat data/depconv/bitbake.curl.task-depends.dot |
     deptransform sub --key=node:label 's/.*//' |
 ```
 
-> [!NOTE]
->
-> The `deptransform` tool shares the same GPL-2.0 license caveat as `depconv` with respect to DOT
-> parsing.
-
 ## depquery
 
 Query properties of dependency graphs. Lists nodes, edges, and computes graph metrics. Supports the
@@ -333,10 +318,74 @@ tracing-subscriber	10
 The `depquery` tool supports outputting `nodes`, `edges`, and `metrics`. The output is intended to
 be machine-readable, and is tab-separated.
 
-> [!NOTE]
->
-> The `depquery` tool shares the same GPL-2.0 license caveat as `depconv` with respect to DOT
-> parsing.
+## depcluster
+
+Run community detection on a dependency graph to identify clusters of related nodes. Each cluster
+becomes a subgraph in the output, with cross-cluster edges at the top level. Supports Louvain
+(default), Leiden, and Label Propagation algorithms.
+
+```sh
+$ echo -e "a b\na c\nb c\nd e\nd f\ne f\n#\na b\na c\nb c\nd e\nd f\ne f" |
+    depcluster -I tgf -O mermaid
+```
+
+```mermaid
+flowchart LR
+    subgraph cluster_0
+        a
+        b
+        c
+        a --> b
+        a --> c
+        b --> c
+    end
+    subgraph cluster_1
+        d
+        e
+        f
+        d --> e
+        d --> f
+        e --> f
+    end
+```
+
+## graphdiff
+
+Compare two dependency graphs and report what changed. Nodes are matched by ID, and edges by their
+endpoints.
+
+`graphdiff` supports several subcommands:
+
+* `graphdiff annotate` -- output the combined graph with changes highlighted (added, removed,
+  changed nodes/edges get distinct attributes)
+* `graphdiff list` -- tab-delimited list of changes (`+` added, `-` removed, `~` changed, `>` moved)
+* `graphdiff summary` -- tab-delimited counts of each change type
+* `graphdiff subtract` -- set difference: nodes and edges only in the first graph
+
+```sh
+$ cat before.tgf
+a Alpha
+b Bravo
+#
+a b
+
+$ cat after.tgf
+b Bravo
+c Charlie
+#
+b c
+
+$ graphdiff annotate before.tgf after.tgf -O mermaid
+```
+
+```mermaid
+flowchart LR
+    b["Bravo"]
+    c["+ Charlie"]
+    a["- Alpha"]
+    b --> c
+    a --> b
+```
 
 ## can2csv
 

From 0283c843936a2e8dcb617a7dcb42182145bda08c Mon Sep 17 00:00:00 2001
From: Austin Gill <Notgnoshi@gmail.com>
Date: Sat, 21 Feb 2026 10:54:00 -0600
Subject: [PATCH 5/6] Reorder sections in the README to group related tools

---
 README.md | 176 +++++++++++++++++++++++++++---------------------------
 1 file changed, 88 insertions(+), 88 deletions(-)

diff --git a/README.md b/README.md
index 85f5af1..ec4c0a0 100644
--- a/README.md
+++ b/README.md
@@ -10,21 +10,21 @@ Gizmos for working with CSVs
 * [csvplot](#csvplot) -- line and scatter plots from CSV files
 * [csvstats](#csvstats) -- histograms and summary statistics for CSV files
 * [csvcat](#csvcat) -- concatenate CSV files
-* [can2k](#can2k) -- parse NMEA 2000 GPS data from CAN logs
-* [qgsdir](#qgsdir) -- generate QGIS projects from directories of CSV files
 * [csvdelta](#csvdelta) -- calculate inter-row deltas for CSV files
-* [minpath](#minpath) -- shorten file paths to minimal unique suffixes
-* [depconv](#depconv) -- convert dependency graphs between formats
-* [depfilter](#depfilter) -- filter or select subsets of dependency graphs
-* [deptransform](#deptransform) -- transform dependency graphs
+* [can2k](#can2k) -- parse NMEA 2000 GPS data from CAN logs
 * [can2csv](#can2csv) -- parse CAN logs into CSV files
 * [canspam](#canspam) -- generate random CAN traffic
 * [canstruct](#canstruct) -- reconstruct NMEA 2000 Fast Packet / ISO 11783-3 Transport Protocol
   sessions
+* [qgsdir](#qgsdir) -- generate QGIS projects from directories of CSV files
+* [depconv](#depconv) -- convert dependency graphs between formats
+* [depfilter](#depfilter) -- filter or select subsets of dependency graphs
+* [deptransform](#deptransform) -- transform dependency graphs
 * [depquery](#depquery) -- query properties of dependency graphs
 * [depcluster](#depcluster) -- cluster dependency graphs using community detection
 * [graphdiff](#graphdiff) -- compare two dependency graphs
 * [bbclasses](#bbclasses) -- generate BitBake recipe inheritance diagrams
+* [minpath](#minpath) -- shorten file paths to minimal unique suffixes
 
 # Philosophy
 
@@ -125,6 +125,27 @@ foo,bar,baz
 7,8,9
 ```
 
+## csvdelta
+
+Calculate the inter-row deltas for a CSV column. Useful for understanding the time between events.
+Also supports mean-centering a column, or centering it around a specific value.
+
+```sh
+$ csvdelta --column foo <<EOF
+foo,bar
+0,a
+1,b
+3,c
+5,d
+EOF
+
+foo,bar,foo-deltas
+0,a,
+1,b,1
+3,c,2
+5,d,2
+```
+
 ## can2k
 
 Parse NMEA 2000 GPS data out of a candump into a CSV file that QGIS can load with minimal effort.
@@ -142,59 +163,65 @@ src,seq_id,longitude_deg,latitude_deg,altitude_m,sog_mps,cog_deg_cwfn,cog_ref,me
 >
 > If you want to use `can2k` together with `qgsdir`, you need to use `can2k --wkt`.
 
-## qgsdir
+## can2csv
 
-Generate a QGIS project from a directory of CSV layer files. Each CSV file is assumed to have a
-column of WKT geometries named `geometry` (QGIS's geometry heuristics don't appear to be exposed via
-their Python API).
+Parse basic data from a CAN frame into a CSV record. Faster than `sed`, and also parses the canid.
+Useful in conjunction with `csvdelta` to understand message timing.
+
+`can2csv` is not a real CAN parser, and does not understand any of the data transmitted via CAN.
 
 ```sh
-$ can2k --wkt ./data/n2k-sample.log ./data/n2k.csv
-$ qgsdir --open ./data/n2k.csv
+$ head -n 3 data/candump-random-data.log | can2csv
+timestamp,interface,canid,dlc,priority,src,dst,pgn,data
+1739229594.465994,can0,0xE9790B5,8,3,0xB5,0x90,0x29700,CA3F871A5A6EE75F
+1739229594.467052,can0,0xD15F192,8,3,0x92,0xF1,0x11500,500B3766CB2DED7C
 ```
 
-You may pass directories or files. If you pass a directory, the script is able to group layers by
-subdirectory, leading to an easier-to-use layer tree.
+If you pass `--reconstruct`, then `can2csv` will reconstruct any transport layer sessions it can
+understand. Right now that's just NMEA 2000 Fast Packet, but ISO-11783 Transport Protocol is
+planned.
 
-## csvdelta
+## canspam
 
-Calculate the inter-row deltas for a CSV column. Useful for understanding the time between events.
-Also supports mean-centering a column, or centering it around a specific value.
+The [canspam](./scripts/canspam) script can generate random CAN traffic on a Linux CAN device. It's
+useful for inflating busload, or for generating random traffic to test `can2csv` against ;)
+
+## canstruct
+
+The `canstruct` tool is a NMEA 2000 Fast Packet / ISO 11783-3 Transport Protocol transport session
+reconstruction tool. That is, you give it the individual 8-byte frames, and it gives you the
+reconstructed messages.
 
 ```sh
-$ csvdelta --column foo <<EOF
-foo,bar
-0,a
-1,b
-3,c
-5,d
-EOF
+$ cat data/abort-then-full.log
+(1750963033.251412) can0 18EC2A1C#101600040400EF00      // TP.CM_RTS
+(1750963033.270725) can0 18EC1C2A#FF01FFFFFF00EF00      // TP.Conn_Abort
+(1750963079.757877) can0 18EC2A1C#101600040400EF00      // TP.CM_RTS
+(1750963079.775206) can0 18EC1C2A#110401FFFF00EF00      // TP.CM_CTS
+(1750963079.778342) can0 14EB2A1C#0111111111111111      // TP.DT
+(1750963079.779468) can0 14EB2A1C#0222222222222222      // TP.DT
+(1750963079.780613) can0 14EB2A1C#0333333333333333      // TP.DT
+(1750963079.781778) can0 14EB2A1C#0444FFFFFFFFFFFF      // TP.DT
+(1750963079.795905) can0 18EC1C2A#13160004FF00EF00      // TP.CM_EndofMsgACK
 
-foo,bar,foo-deltas
-0,a,
-1,b,1
-3,c,2
-5,d,2
+$ canstruct data/abort-then-full.log
+2025-06-28T15:36:19.051620Z  WARN csvizmo::can::tp: TP.CM_ABRT 0x1C <- 0x2A reason ExistingTransportSession pgn 0xEF00
+(1750963079.795905) can0 18EF2A1C#11111111111111222222222222223333333333333344
 ```
 
-## minpath
+## qgsdir
 
-Shorten file paths to the minimal unique suffix. Useful for displaying lists of files in a compact
-way while keeping them distinguishable.
+Generate a QGIS project from a directory of CSV layer files. Each CSV file is assumed to have a
+column of WKT geometries named `geometry` (QGIS's geometry heuristics don't appear to be exposed via
+their Python API).
 
 ```sh
-$ minpath <<EOF
-/home/user/project/src/main.rs
-/home/user/project/src/lib.rs
-/home/user/project/tests/main.rs
-EOF
-
-src/main.rs
-lib.rs
-tests/main.rs
+$ can2k --wkt ./data/n2k-sample.log ./data/n2k.csv
+$ qgsdir --open ./data/n2k.csv
 ```
 
-Multiple options are available to customize and tune the output. See `minpath --help` for details.
+You may pass directories or files. If you pass a directory, the script is able to group layers by
+subdirectory, leading to an easier-to-use layer tree.
 
 ## depconv
 
@@ -387,52 +414,6 @@ flowchart LR
     a --> b
 ```
 
-## can2csv
-
-Parse basic data from a CAN frame into a CSV record. Faster than `sed`, and also parses the canid.
-Useful in conjunction with `csvdelta` to understand message timing.
-
-`can2csv` is not a real CAN parser, and does not understand any of the data transmitted via CAN.
-
-```sh
-$ head -n 3 data/candump-random-data.log | can2csv
-timestamp,interface,canid,dlc,priority,src,dst,pgn,data
-1739229594.465994,can0,0xE9790B5,8,3,0xB5,0x90,0x29700,CA3F871A5A6EE75F
-1739229594.467052,can0,0xD15F192,8,3,0x92,0xF1,0x11500,500B3766CB2DED7C
-```
-
-If you pass `--reconstruct`, then `can2csv` will reconstruct any transport layer sessions it can
-understand. Right now that's just NMEA 2000 Fast Packet, but ISO-11783 Transport Protocol is
-planned.
-
-## canspam
-
-The [canspam](./scripts/canspam) script can generate random CAN traffic on a Linux CAN device. It's
-useful for inflating busload, or for generating random traffic to test `can2csv` against ;)
-
-## canstruct
-
-The `canstruct` tool is a NMEA 2000 Fast Packet / ISO 11783-3 Transport Protocol transport session
-reconstruction tool. That is, you give it the individual 8-byte frames, and it gives you the
-reconstructed messages.
-
-```sh
-$ cat data/abort-then-full.log
-(1750963033.251412) can0 18EC2A1C#101600040400EF00      // TP.CM_RTS
-(1750963033.270725) can0 18EC1C2A#FF01FFFFFF00EF00      // TP.Conn_Abort
-(1750963079.757877) can0 18EC2A1C#101600040400EF00      // TP.CM_RTS
-(1750963079.775206) can0 18EC1C2A#110401FFFF00EF00      // TP.CM_CTS
-(1750963079.778342) can0 14EB2A1C#0111111111111111      // TP.DT
-(1750963079.779468) can0 14EB2A1C#0222222222222222      // TP.DT
-(1750963079.780613) can0 14EB2A1C#0333333333333333      // TP.DT
-(1750963079.781778) can0 14EB2A1C#0444FFFFFFFFFFFF      // TP.DT
-(1750963079.795905) can0 18EC1C2A#13160004FF00EF00      // TP.CM_EndofMsgACK
-
-$ canstruct data/abort-then-full.log
-2025-06-28T15:36:19.051620Z  WARN csvizmo::can::tp: TP.CM_ABRT 0x1C <- 0x2A reason ExistingTransportSession pgn 0xEF00
-(1750963079.795905) can0 18EF2A1C#11111111111111222222222222223333333333333344
-```
-
 ## bbclasses
 
 The [bbclasses](./scripts/bbclasses) script can parse BitBake recipes to generate an inheritance
@@ -502,3 +483,22 @@ flowchart LR
     poky/meta/conf/distro/include/ptest-packagelists.inc -->|"require"| poky/meta/classes-recipe/ptest.bbclass
     poky/meta/recipes-support/curl/curl_8.7.1.bb -->|"appends"| meta-work/recipes-support/curl/curl__.bbappend
 ```
+
+## minpath
+
+Shorten file paths to the minimal unique suffix. Useful for displaying lists of files in a compact
+way while keeping them distinguishable.
+
+```sh
+$ minpath <<EOF
+/home/user/project/src/main.rs
+/home/user/project/src/lib.rs
+/home/user/project/tests/main.rs
+EOF
+
+src/main.rs
+lib.rs
+tests/main.rs
+```
+
+Multiple options are available to customize and tune the output. See `minpath --help` for details.

From b066f237d1b2801680ec113f9952fe1a92c500dd Mon Sep 17 00:00:00 2001
From: Austin Gill <Notgnoshi@gmail.com>
Date: Sat, 21 Feb 2026 11:00:25 -0600
Subject: [PATCH 6/6] Add depfilter slice subcommand

---
 crates/csvizmo-depgraph/src/algorithm/mod.rs  |   1 +
 .../csvizmo-depgraph/src/algorithm/slice.rs   | 327 ++++++++++++++++++
 crates/csvizmo-depgraph/src/bin/depfilter.rs  |   4 +
 crates/csvizmo-depgraph/tests/depfilter.rs    | 186 ++++++++++
 4 files changed, 518 insertions(+)
 create mode 100644 crates/csvizmo-depgraph/src/algorithm/slice.rs

diff --git a/crates/csvizmo-depgraph/src/algorithm/mod.rs b/crates/csvizmo-depgraph/src/algorithm/mod.rs
index 7cf9471..4cfa1c0 100644
--- a/crates/csvizmo-depgraph/src/algorithm/mod.rs
+++ b/crates/csvizmo-depgraph/src/algorithm/mod.rs
@@ -9,6 +9,7 @@ pub mod reverse;
 pub mod select;
 pub mod shorten;
 pub mod simplify;
+pub mod slice;
 pub mod sub;
 
 use globset::{Glob, GlobSet, GlobSetBuilder};
diff --git a/crates/csvizmo-depgraph/src/algorithm/slice.rs b/crates/csvizmo-depgraph/src/algorithm/slice.rs
new file mode 100644
index 0000000..c0417a6
--- /dev/null
+++ b/crates/csvizmo-depgraph/src/algorithm/slice.rs
@@ -0,0 +1,327 @@
+use std::collections::HashMap;
+
+use clap::Parser;
+
+use crate::{DepGraph, Edge, NodeInfo};
+
+/// Cut edges between subgraphs, isolating each subgraph.
+#[derive(Clone, Debug, Default, Parser)]
+pub struct SliceArgs {
+    /// Remove nodes that are not inside any subgraph.
+    #[clap(long)]
+    pub drop_orphans: bool,
+
+    /// Also slice within nested subgraphs recursively.
+    #[clap(short, long)]
+    pub recursive: bool,
+}
+
+/// Cut edges that cross subgraph boundaries, isolating each subgraph into a
+/// disconnected component.
+///
+/// In the default (top-level) mode, every node is assigned to the top-level
+/// subgraph it belongs to (even if nested deeper). Edges are kept only when
+/// both endpoints share the same top-level group. With `--drop-orphans`,
+/// root-level nodes (not inside any subgraph) and their edges are also removed.
+///
+/// In `--recursive` mode, the same logic is applied independently at each level
+/// of the subgraph hierarchy: edges at a given level are kept only when both
+/// endpoints belong to the same immediate child subgraph (or are both
+/// root-level at that scope).
+pub fn slice(graph: &DepGraph, args: &SliceArgs) -> eyre::Result<DepGraph> {
+    if args.recursive {
+        Ok(slice_recursive(graph, args.drop_orphans))
+    } else {
+        Ok(slice_toplevel(graph, args.drop_orphans))
+    }
+}
+
+/// Recursively assign all nodes in `sg` (and its nested subgraphs) to `group`.
+fn assign_group(sg: &DepGraph, map: &mut HashMap<String, usize>, group: usize) {
+    for id in sg.nodes.keys() {
+        map.insert(id.clone(), group);
+    }
+    for child in &sg.subgraphs {
+        assign_group(child, map, group);
+    }
+}
+
+/// Check if an edge should be kept based on the group map.
+///
+/// An edge is kept when both endpoints belong to the same group. Endpoints not
+/// present in the map are considered root-level; two root-level endpoints are
+/// kept unless `drop_orphans` is true.
+fn edge_allowed(edge: &Edge, group_map: &HashMap<String, usize>, drop_orphans: bool) -> bool {
+    match (group_map.get(&edge.from), group_map.get(&edge.to)) {
+        (Some(f), Some(t)) => f == t,
+        (None, None) => !drop_orphans,
+        _ => false,
+    }
+}
+
+/// Filter nodes at one level: drop root-level nodes when `drop_orphans` is set.
+fn filter_nodes(
+    graph: &DepGraph,
+    group_map: &HashMap<String, usize>,
+    drop_orphans: bool,
+) -> indexmap::IndexMap<String, NodeInfo> {
+    if drop_orphans {
+        graph
+            .nodes
+            .iter()
+            .filter(|(id, _)| group_map.contains_key(id.as_str()))
+            .map(|(id, info)| (id.clone(), info.clone()))
+            .collect()
+    } else {
+        graph.nodes.clone()
+    }
+}
+
+fn slice_toplevel(graph: &DepGraph, drop_orphans: bool) -> DepGraph {
+    let mut group_map = HashMap::new();
+    for (i, sg) in graph.subgraphs.iter().enumerate() {
+        assign_group(sg, &mut group_map, i);
+    }
+    rebuild(graph, &group_map, drop_orphans)
+}
+
+/// Rebuild the graph tree, filtering edges using a global group map.
+fn rebuild(graph: &DepGraph, group_map: &HashMap<String, usize>, drop_orphans: bool) -> DepGraph {
+    let nodes = filter_nodes(graph, group_map, drop_orphans);
+    let edges: Vec<Edge> = graph
+        .edges
+        .iter()
+        .filter(|e| edge_allowed(e, group_map, drop_orphans))
+        .cloned()
+        .collect();
+    let subgraphs = graph
+        .subgraphs
+        .iter()
+        .map(|sg| rebuild(sg, group_map, drop_orphans))
+        .collect();
+
+    DepGraph {
+        id: graph.id.clone(),
+        attrs: graph.attrs.clone(),
+        nodes,
+        edges,
+        subgraphs,
+        ..Default::default()
+    }
+}
+
+fn slice_recursive(graph: &DepGraph, drop_orphans: bool) -> DepGraph {
+    // Nothing to slice at a leaf level (no subgraph boundaries).
+    if graph.subgraphs.is_empty() {
+        return DepGraph {
+            id: graph.id.clone(),
+            attrs: graph.attrs.clone(),
+            nodes: graph.nodes.clone(),
+            edges: graph.edges.clone(),
+            subgraphs: vec![],
+            ..Default::default()
+        };
+    }
+
+    let mut group_map = HashMap::new();
+    for (i, sg) in graph.subgraphs.iter().enumerate() {
+        assign_group(sg, &mut group_map, i);
+    }
+
+    let nodes = filter_nodes(graph, &group_map, drop_orphans);
+    let edges: Vec<Edge> = graph
+        .edges
+        .iter()
+        .filter(|e| edge_allowed(e, &group_map, drop_orphans))
+        .cloned()
+        .collect();
+    let subgraphs = graph
+        .subgraphs
+        .iter()
+        .map(|sg| slice_recursive(sg, drop_orphans))
+        .collect();
+
+    DepGraph {
+        id: graph.id.clone(),
+        attrs: graph.attrs.clone(),
+        nodes,
+        edges,
+        subgraphs,
+        ..Default::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_graph(nodes: &[&str], edges: &[(&str, &str)], subgraphs: Vec<DepGraph>) -> DepGraph {
+        DepGraph {
+            nodes: nodes
+                .iter()
+                .map(|id| (id.to_string(), NodeInfo::new(*id)))
+                .collect(),
+            edges: edges
+                .iter()
+                .map(|(from, to)| Edge {
+                    from: from.to_string(),
+                    to: to.to_string(),
+                    ..Default::default()
+                })
+                .collect(),
+            subgraphs,
+            ..Default::default()
+        }
+    }
+
+    fn node_ids(graph: &DepGraph) -> Vec<&str> {
+        graph.nodes.keys().map(|s| s.as_str()).collect()
+    }
+
+    fn edge_pairs(graph: &DepGraph) -> Vec<(&str, &str)> {
+        graph
+            .edges
+            .iter()
+            .map(|e| (e.from.as_str(), e.to.as_str()))
+            .collect()
+    }
+
+    #[test]
+    fn empty_graph() {
+        let g = DepGraph::default();
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        assert!(result.nodes.is_empty());
+        assert!(result.edges.is_empty());
+        assert!(result.subgraphs.is_empty());
+    }
+
+    #[test]
+    fn no_subgraphs_preserves_all() {
+        let g = make_graph(&["a", "b"], &[("a", "b")], vec![]);
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        assert_eq!(node_ids(&result), vec!["a", "b"]);
+        assert_eq!(edge_pairs(&result), vec![("a", "b")]);
+    }
+
+    #[test]
+    fn no_subgraphs_drop_orphans_removes_all() {
+        let g = make_graph(&["a", "b"], &[("a", "b")], vec![]);
+        let args = SliceArgs {
+            drop_orphans: true,
+            ..Default::default()
+        };
+        let result = slice(&g, &args).unwrap();
+        assert!(result.nodes.is_empty());
+        assert!(result.edges.is_empty());
+    }
+
+    #[test]
+    fn cross_subgraph_edges_removed() {
+        let sg0 = make_graph(&["a"], &[], vec![]);
+        let sg1 = make_graph(&["b"], &[], vec![]);
+        let g = make_graph(&[], &[("a", "b")], vec![sg0, sg1]);
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        assert!(result.edges.is_empty());
+    }
+
+    #[test]
+    fn intra_subgraph_edges_preserved() {
+        let sg = make_graph(&["a", "b"], &[], vec![]);
+        let g = make_graph(&[], &[("a", "b")], vec![sg]);
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        assert_eq!(edge_pairs(&result), vec![("a", "b")]);
+    }
+
+    #[test]
+    fn root_to_subgraph_edges_removed() {
+        let sg = make_graph(&["b"], &[], vec![]);
+        let g = make_graph(&["a"], &[("a", "b")], vec![sg]);
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        assert!(result.edges.is_empty());
+        assert_eq!(node_ids(&result), vec!["a"]);
+    }
+
+    #[test]
+    fn root_nodes_preserved_by_default() {
+        let sg = make_graph(&["b"], &[], vec![]);
+        let g = make_graph(&["a"], &[], vec![sg]);
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        assert_eq!(node_ids(&result), vec!["a"]);
+    }
+
+    #[test]
+    fn drop_orphans_removes_root_nodes_and_edges() {
+        let sg = make_graph(&["b", "c"], &[], vec![]);
+        let g = make_graph(&["a"], &[("a", "b"), ("b", "c")], vec![sg]);
+        let args = SliceArgs {
+            drop_orphans: true,
+            ..Default::default()
+        };
+        let result = slice(&g, &args).unwrap();
+        assert!(result.nodes.is_empty());
+        // b->c kept (both in same group), a->b dropped (cross-boundary)
+        assert_eq!(edge_pairs(&result), vec![("b", "c")]);
+    }
+
+    #[test]
+    fn nested_subgraph_toplevel_groups_under_outermost() {
+        let inner = make_graph(&["c"], &[], vec![]);
+        let outer = make_graph(&["a"], &[], vec![inner]);
+        let g = make_graph(&[], &[("a", "c")], vec![outer]);
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        // Both a and c belong to the same top-level group
+        assert_eq!(edge_pairs(&result), vec![("a", "c")]);
+    }
+
+    #[test]
+    fn recursive_cuts_within_nested_subgraphs() {
+        let inner = make_graph(&["b"], &[], vec![]);
+        let outer = make_graph(&["a"], &[("a", "b")], vec![inner]);
+        let g = make_graph(&[], &[], vec![outer]);
+
+        // Top-level: a and b both in group 0, edge preserved inside the subgraph
+        let result_toplevel = slice(&g, &SliceArgs::default()).unwrap();
+        assert_eq!(edge_pairs(&result_toplevel.subgraphs[0]), vec![("a", "b")]);
+
+        // Recursive: at the outer subgraph level, a is root, b is in inner -> cut
+        let args = SliceArgs {
+            recursive: true,
+            ..Default::default()
+        };
+        let result_recursive = slice(&g, &args).unwrap();
+        assert!(result_recursive.subgraphs[0].edges.is_empty());
+    }
+
+    #[test]
+    fn recursive_drop_orphans_at_each_level() {
+        let inner = make_graph(&["b"], &[], vec![]);
+        let outer = make_graph(&["a"], &[("a", "b")], vec![inner]);
+        let g = make_graph(&[], &[], vec![outer]);
+
+        let args = SliceArgs {
+            recursive: true,
+            drop_orphans: true,
+        };
+        let result = slice(&g, &args).unwrap();
+        // a is an orphan at the outer subgraph level -> dropped
+        assert!(result.subgraphs[0].nodes.is_empty());
+        assert!(result.subgraphs[0].edges.is_empty());
+        // b is in the inner subgraph -> preserved
+        assert_eq!(node_ids(&result.subgraphs[0].subgraphs[0]), vec!["b"]);
+    }
+
+    #[test]
+    fn subgraph_attrs_and_id_preserved() {
+        let mut sg = make_graph(&["a"], &[], vec![]);
+        sg.id = Some("cluster_0".to_string());
+        sg.attrs.insert("color".to_string(), "blue".to_string());
+        let g = make_graph(&[], &[], vec![sg]);
+
+        let result = slice(&g, &SliceArgs::default()).unwrap();
+        assert_eq!(result.subgraphs[0].id.as_deref(), Some("cluster_0"));
+        assert_eq!(
+            result.subgraphs[0].attrs.get("color").map(String::as_str),
+            Some("blue")
+        );
+    }
+}
diff --git a/crates/csvizmo-depgraph/src/bin/depfilter.rs b/crates/csvizmo-depgraph/src/bin/depfilter.rs
index 0234dd2..c9c57d1 100644
--- a/crates/csvizmo-depgraph/src/bin/depfilter.rs
+++ b/crates/csvizmo-depgraph/src/bin/depfilter.rs
@@ -6,6 +6,7 @@ use csvizmo_depgraph::algorithm;
 use csvizmo_depgraph::algorithm::between::BetweenArgs;
 use csvizmo_depgraph::algorithm::cycles::CyclesArgs;
 use csvizmo_depgraph::algorithm::select::SelectArgs;
+use csvizmo_depgraph::algorithm::slice::SliceArgs;
 use csvizmo_depgraph::emit::OutputFormat;
 use csvizmo_depgraph::parse::InputFormat;
 use csvizmo_utils::stdio::{get_input_reader, get_output_writer};
@@ -49,6 +50,8 @@ enum Command {
     Between(BetweenArgs),
     /// Detect cycles (strongly connected components) and output each as a subgraph
     Cycles(CyclesArgs),
+    /// Cut edges between subgraphs, isolating each subgraph
+    Slice(SliceArgs),
 }
 
 fn main() -> eyre::Result<()> {
@@ -98,6 +101,7 @@ fn main() -> eyre::Result<()> {
         Command::Select(select_args) => algorithm::select::select(&graph, select_args)?,
         Command::Between(between_args) => algorithm::between::between(&graph, between_args)?,
         Command::Cycles(cycles_args) => algorithm::cycles::cycles(&graph, cycles_args)?,
+        Command::Slice(slice_args) => algorithm::slice::slice(&graph, slice_args)?,
     };
 
     let mut output = get_output_writer(&output_path)?;
diff --git a/crates/csvizmo-depgraph/tests/depfilter.rs b/crates/csvizmo-depgraph/tests/depfilter.rs
index 8e13e36..05173e0 100644
--- a/crates/csvizmo-depgraph/tests/depfilter.rs
+++ b/crates/csvizmo-depgraph/tests/depfilter.rs
@@ -730,3 +730,189 @@ fn cycles_self_loop_ignored() {
     let stdout = String::from_utf8_lossy(&output.stdout);
     assert_eq!(stdout, "#\n");
 }
+
+// -- slice integration tests --
+
+#[cfg(feature = "dot")]
+#[test]
+fn slice_removes_cross_subgraph_edges() {
+    let dot_input = "\
+digraph {
+    subgraph cluster_0 {
+        a;
+    }
+    subgraph cluster_1 {
+        b;
+    }
+    a -> b;
+}
+";
+    let output = tool!("depfilter")
+        .args(["slice", "--input-format", "dot", "--output-format", "dot"])
+        .write_stdin(dot_input)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_0 {
+        a;
+    }
+    subgraph cluster_1 {
+        b;
+    }
+}
+"
+    );
+}
+
+#[cfg(feature = "dot")]
+#[test]
+fn slice_preserves_root_nodes_by_default() {
+    let dot_input = "\
+digraph {
+    subgraph cluster_0 {
+        a;
+    }
+    orphan;
+    orphan -> a;
+}
+";
+    let output = tool!("depfilter")
+        .args(["slice", "--input-format", "dot", "--output-format", "dot"])
+        .write_stdin(dot_input)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_0 {
+        a;
+    }
+    orphan;
+}
+"
+    );
+}
+
+#[cfg(feature = "dot")]
+#[test]
+fn slice_drop_orphans() {
+    let dot_input = "\
+digraph {
+    subgraph cluster_0 {
+        a;
+    }
+    orphan;
+    orphan -> a;
+}
+";
+    let output = tool!("depfilter")
+        .args([
+            "slice",
+            "--drop-orphans",
+            "--input-format",
+            "dot",
+            "--output-format",
+            "dot",
+        ])
+        .write_stdin(dot_input)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_0 {
+        a;
+    }
+}
+"
+    );
+}
+
+#[test]
+fn slice_no_subgraphs() {
+    let graph = "a\nb\n#\na\tb\n";
+    let output = tool!("depfilter")
+        .args(["slice", "--input-format", "tgf", "--output-format", "tgf"])
+        .write_stdin(graph)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "a\nb\n#\na\tb\n");
+}
+
+#[test]
+fn slice_no_subgraphs_drop_orphans() {
+    let graph = "a\nb\n#\na\tb\n";
+    let output = tool!("depfilter")
+        .args([
+            "slice",
+            "--drop-orphans",
+            "--input-format",
+            "tgf",
+            "--output-format",
+            "tgf",
+        ])
+        .write_stdin(graph)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(stdout, "#\n");
+}
+
+#[cfg(feature = "dot")]
+#[test]
+fn slice_recursive() {
+    // Outer subgraph has node a and a nested inner subgraph with node b.
+    // Edge a -> b crosses the inner boundary; recursive mode should cut it.
+    let dot_input = "\
+digraph {
+    subgraph cluster_outer {
+        subgraph cluster_inner {
+            b;
+        }
+        a;
+        a -> b;
+    }
+}
+";
+    let output = tool!("depfilter")
+        .args([
+            "slice",
+            "--recursive",
+            "--input-format",
+            "dot",
+            "--output-format",
+            "dot",
+        ])
+        .write_stdin(dot_input)
+        .captured_output()
+        .unwrap();
+    assert!(output.status.success());
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert_eq!(
+        stdout,
+        "\
+digraph {
+    subgraph cluster_outer {
+        subgraph cluster_inner {
+            b;
+        }
+        a;
+    }
+}
+"
+    );
+}