Merge pull request #248 from egohygiene/copilot/build-minimal-dag-multi-target

feat: Build minimal DAG for multi-target execution

Author: szmyty

src/graph/mod.rs

@@ -1,8 +1,10 @@
 mod format;
+mod multi_target;
 mod pathfinding;
 mod transform_edge;
 
 pub use format::Format;
+pub use multi_target::MultiTargetDag;
 pub use pathfinding::TransformPath;
 pub use transform_edge::TransformEdge;
 
@@ -189,6 +191,52 @@ impl TransformGraph {
         });
         paths
     }
+
+    /// Build a minimal DAG that covers all `targets` reachable from `from`.
+    ///
+    /// For each target the cheapest path is computed independently via
+    /// [`find_path`](Self::find_path).  All resulting edges are then merged
+    /// into a single [`MultiTargetDag`], deduplicating any edges that are
+    /// shared across paths.  When two paths contribute an edge for the same
+    /// `(from, to)` pair the cheaper edge is kept.
+    ///
+    /// Returns `None` when at least one target is unreachable from `from`.
+    /// Returns `Some` with an empty DAG when `targets` is empty.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use renderflow::graph::{Format, TransformEdge, TransformGraph};
+    ///
+    /// let mut graph = TransformGraph::new();
+    /// graph.add_transform(TransformEdge::new(Format::Markdown, Format::Html, 0.5, 1.0));
+    /// graph.add_transform(TransformEdge::new(Format::Html, Format::Pdf,  0.8, 0.85));
+    /// graph.add_transform(TransformEdge::new(Format::Html, Format::Docx, 0.6, 0.90));
+    ///
+    /// let dag = graph
+    ///     .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+    ///     .expect("all targets must be reachable");
+    ///
+    /// // Markdown → Html is shared: 3 unique edges, not 4.
+    /// assert_eq!(dag.edge_count(), 3);
+    ///
+    /// let order = dag.execution_order();
+    /// assert_eq!(order.len(), 3);
+    /// ```
+    pub fn build_multi_target_dag(
+        &self,
+        from: Format,
+        targets: &[Format],
+    ) -> Option<MultiTargetDag> {
+        let mut dag = MultiTargetDag::new();
+        for &target in targets {
+            let path = self.find_path(from, target)?;
+            for edge in path.steps {
+                dag.merge_edge(edge);
+            }
+        }
+        Some(dag)
+    }
 }
 
 impl Default for TransformGraph {

src/graph/multi_target.rs

@@ -0,0 +1,327 @@
+use super::{Format, TransformEdge};
+
+use petgraph::graph::{DiGraph, NodeIndex};
+use petgraph::visit::EdgeRef;
+use std::collections::HashMap;
+
+/// A minimal directed acyclic graph that merges the cheapest transformation
+/// paths for several output targets from a single source format.
+///
+/// Intermediate nodes (e.g. `Html` when producing both `Pdf` and `Docx` from
+/// `Markdown`) are reused across paths so that each transformation step is
+/// represented exactly once in the DAG.
+///
+/// # Example
+///
+/// ```rust
+/// use renderflow::graph::{Format, TransformEdge, TransformGraph};
+///
+/// let mut graph = TransformGraph::new();
+/// graph.add_transform(TransformEdge::new(Format::Markdown, Format::Html, 0.5, 1.0));
+/// graph.add_transform(TransformEdge::new(Format::Html, Format::Pdf,  0.8, 0.85));
+/// graph.add_transform(TransformEdge::new(Format::Html, Format::Docx, 0.6, 0.90));
+///
+/// let dag = graph
+///     .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+///     .expect("all targets must be reachable");
+///
+/// // Markdown → Html is shared: only 3 unique edges total.
+/// assert_eq!(dag.edge_count(), 3);
+/// assert!(dag.contains_edge(Format::Markdown, Format::Html));
+/// assert!(dag.contains_edge(Format::Html, Format::Pdf));
+/// assert!(dag.contains_edge(Format::Html, Format::Docx));
+///
+/// // Execution order respects dependencies.
+/// let order = dag.execution_order();
+/// assert_eq!(order.len(), 3);
+/// ```
+pub struct MultiTargetDag {
+    pub(super) graph: DiGraph<Format, TransformEdge>,
+    pub(super) nodes: HashMap<Format, NodeIndex>,
+}
+
+impl MultiTargetDag {
+    pub(super) fn new() -> Self {
+        Self {
+            graph: DiGraph::new(),
+            nodes: HashMap::new(),
+        }
+    }
+
+    /// Return the [`NodeIndex`] for `format`, inserting a node when one does
+    /// not already exist.
+    pub(super) fn get_or_insert_node(&mut self, format: Format) -> NodeIndex {
+        if let Some(&idx) = self.nodes.get(&format) {
+            idx
+        } else {
+            let idx = self.graph.add_node(format);
+            self.nodes.insert(format, idx);
+            idx
+        }
+    }
+
+    /// Merge `edge` into the DAG.
+    ///
+    /// If an edge between the same `(from, to)` pair already exists, the one
+    /// with the lower cost is kept and the other is discarded.  This ensures
+    /// that a shared intermediate step always executes via the cheapest
+    /// available transformation.
+    pub(super) fn merge_edge(&mut self, edge: TransformEdge) {
+        let from_idx = self.get_or_insert_node(edge.from);
+        let to_idx = self.get_or_insert_node(edge.to);
+
+        // Check whether an edge for this (from, to) pair is already present.
+        let existing_id = self
+            .graph
+            .edges(from_idx)
+            .find(|e| e.target() == to_idx)
+            .map(|e| e.id());
+
+        if let Some(id) = existing_id {
+            // Keep the cheaper edge.
+            if edge.cost < self.graph[id].cost {
+                self.graph[id] = edge;
+            }
+        } else {
+            self.graph.add_edge(from_idx, to_idx, edge);
+        }
+    }
+
+    /// Return the edges in a valid topological execution order.
+    ///
+    /// Each [`TransformEdge`] in the returned `Vec` is guaranteed to appear
+    /// only after all edges that produce its source format.  An empty `Vec` is
+    /// returned when the graph contains a cycle (which should never occur for a
+    /// well-formed transformation DAG).
+    pub fn execution_order(&self) -> Vec<&TransformEdge> {
+        use petgraph::algo::toposort;
+
+        let sorted_nodes = match toposort(&self.graph, None) {
+            Ok(nodes) => nodes,
+            Err(_) => return Vec::new(),
+        };
+
+        let mut result = Vec::new();
+        for node in &sorted_nodes {
+            for edge_ref in self.graph.edges(*node) {
+                result.push(edge_ref.weight());
+            }
+        }
+        result
+    }
+
+    /// Return all edges stored in the DAG (in arbitrary order).
+    pub fn all_edges(&self) -> Vec<&TransformEdge> {
+        self.graph.edge_weights().collect()
+    }
+
+    /// Return `true` when a direct edge from `from` to `to` exists in the DAG.
+    pub fn contains_edge(&self, from: Format, to: Format) -> bool {
+        let (Some(&fi), Some(&ti)) = (self.nodes.get(&from), self.nodes.get(&to)) else {
+            return false;
+        };
+        self.graph.contains_edge(fi, ti)
+    }
+
+    /// Return the number of unique edges in the DAG.
+    pub fn edge_count(&self) -> usize {
+        self.graph.edge_count()
+    }
+
+    /// Return the number of unique format nodes in the DAG.
+    pub fn node_count(&self) -> usize {
+        self.graph.node_count()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::graph::TransformGraph;
+
+    fn build_graph() -> TransformGraph {
+        let mut g = TransformGraph::new();
+        // Markdown → Html (0.5 / 1.0)
+        g.add_transform(TransformEdge::new(Format::Markdown, Format::Html, 0.5, 1.0));
+        // Html → Pdf  (0.8 / 0.85)
+        g.add_transform(TransformEdge::new(Format::Html, Format::Pdf, 0.8, 0.85));
+        // Html → Docx (0.6 / 0.90)
+        g.add_transform(TransformEdge::new(Format::Html, Format::Docx, 0.6, 0.90));
+        g
+    }
+
+    // ── build_multi_target_dag ────────────────────────────────────────────────
+
+    #[test]
+    fn test_dag_shared_intermediate_not_duplicated() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        // Markdown → Html is shared; only 3 unique edges total.
+        assert_eq!(dag.edge_count(), 3);
+    }
+
+    #[test]
+    fn test_dag_contains_expected_edges() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        assert!(dag.contains_edge(Format::Markdown, Format::Html));
+        assert!(dag.contains_edge(Format::Html, Format::Pdf));
+        assert!(dag.contains_edge(Format::Html, Format::Docx));
+    }
+
+    #[test]
+    fn test_dag_single_target_equals_path() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf])
+            .unwrap();
+
+        assert_eq!(dag.edge_count(), 2);
+        assert!(dag.contains_edge(Format::Markdown, Format::Html));
+        assert!(dag.contains_edge(Format::Html, Format::Pdf));
+    }
+
+    #[test]
+    fn test_dag_empty_targets_returns_empty_dag() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[])
+            .unwrap();
+
+        assert_eq!(dag.edge_count(), 0);
+        assert_eq!(dag.node_count(), 0);
+    }
+
+    #[test]
+    fn test_dag_unreachable_target_returns_none() {
+        let mut g = TransformGraph::new();
+        g.add_transform(TransformEdge::new(Format::Markdown, Format::Html, 0.5, 1.0));
+
+        // Epub is not reachable.
+        let result = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Html, Format::Epub]);
+        assert!(result.is_none());
+    }
+
+    // ── execution_order ───────────────────────────────────────────────────────
+
+    #[test]
+    fn test_execution_order_length() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        let order = dag.execution_order();
+        assert_eq!(order.len(), 3);
+    }
+
+    #[test]
+    fn test_execution_order_source_before_dependents() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        let order = dag.execution_order();
+
+        // Find all three positions in a single pass.
+        let mut md_html_pos = None;
+        let mut html_pdf_pos = None;
+        let mut html_docx_pos = None;
+        for (i, e) in order.iter().enumerate() {
+            match (e.from, e.to) {
+                (Format::Markdown, Format::Html) => md_html_pos = Some(i),
+                (Format::Html, Format::Pdf) => html_pdf_pos = Some(i),
+                (Format::Html, Format::Docx) => html_docx_pos = Some(i),
+                _ => {}
+            }
+        }
+
+        let md_html_pos = md_html_pos.expect("Markdown→Html edge must be present");
+        let html_pdf_pos = html_pdf_pos.expect("Html→Pdf edge must be present");
+        let html_docx_pos = html_docx_pos.expect("Html→Docx edge must be present");
+
+        assert!(
+            md_html_pos < html_pdf_pos,
+            "Markdown→Html must precede Html→Pdf"
+        );
+        assert!(
+            md_html_pos < html_docx_pos,
+            "Markdown→Html must precede Html→Docx"
+        );
+    }
+
+    #[test]
+    fn test_execution_order_no_duplicates() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        let order = dag.execution_order();
+        // Build a list of (from, to) pairs and ensure they are all unique.
+        let mut seen = std::collections::HashSet::new();
+        for edge in &order {
+            let pair = (edge.from, edge.to);
+            assert!(seen.insert(pair), "duplicate edge in execution order: {:?}", pair);
+        }
+    }
+
+    // ── edge deduplication (cheaper edge wins) ────────────────────────────────
+
+    #[test]
+    fn test_merge_edge_deduplicates_and_keeps_cheaper() {
+        let mut dag = MultiTargetDag::new();
+        // Add the same (from, to) pair twice: expensive first, then cheaper.
+        dag.merge_edge(TransformEdge::new(Format::Markdown, Format::Html, 2.0, 0.9));
+        dag.merge_edge(TransformEdge::new(Format::Markdown, Format::Html, 1.0, 0.95));
+
+        // Only one edge should be stored.
+        assert_eq!(dag.edge_count(), 1);
+        // The cheaper edge (cost 1.0) must be kept.
+        let edges = dag.all_edges();
+        assert!((edges[0].cost - 1.0).abs() < 1e-5);
+    }
+
+    #[test]
+    fn test_merge_edge_retains_existing_when_new_is_more_expensive() {
+        let mut dag = MultiTargetDag::new();
+        // Add the cheaper edge first, then try to replace it with a more expensive one.
+        dag.merge_edge(TransformEdge::new(Format::Markdown, Format::Html, 1.0, 0.95));
+        dag.merge_edge(TransformEdge::new(Format::Markdown, Format::Html, 2.0, 0.9));
+
+        assert_eq!(dag.edge_count(), 1);
+        let edges = dag.all_edges();
+        assert!((edges[0].cost - 1.0).abs() < 1e-5);
+    }
+
+    #[test]
+    fn test_node_count_shared_intermediate() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        // Nodes: Markdown, Html, Pdf, Docx = 4
+        assert_eq!(dag.node_count(), 4);
+    }
+
+    // ── all_edges ─────────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_all_edges_count_matches_edge_count() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        assert_eq!(dag.all_edges().len(), dag.edge_count());
+    }
+}