Merge pull request #278 from egohygiene/copilot/add-collection-based-transforms

feat: add InputKind for collection-based (multi-input) transforms

Author: szmyty

src/graph/definition.rs

@@ -1,4 +1,4 @@
-use super::{Format, TransformEdge};
+use super::{Format, InputKind, TransformEdge};
 
 /// A pluggable definition of a format-to-format transformation.
 ///
@@ -12,15 +12,19 @@ use super::{Format, TransformEdge};
 /// `"pandoc"` or `"wkhtmltopdf"`), which helps with diagnostics and lets
 /// callers register multiple competing definitions for the same format pair.
 ///
+/// The `input_kind` field controls whether the definition expects a single
+/// source document or a collection of source documents as input.
+///
 /// # Example
 ///
 /// ```rust
-/// use renderflow::graph::{Format, TransformDefinition};
+/// use renderflow::graph::{Format, InputKind, TransformDefinition};
 ///
 /// let def = TransformDefinition::new(Format::Markdown, Format::Html, 0.5, 1.0, "pandoc");
 /// assert_eq!(def.from, Format::Markdown);
 /// assert_eq!(def.to, Format::Html);
 /// assert_eq!(def.label, "pandoc");
+/// assert_eq!(def.input_kind, InputKind::Single);
 /// ```
 #[derive(Debug, Clone, PartialEq)]
 pub struct TransformDefinition {
@@ -34,10 +38,12 @@ pub struct TransformDefinition {
     pub quality: f32,
     /// Human-readable label identifying the tool or method (e.g. `"pandoc"`).
     pub label: String,
+    /// Whether this definition consumes a single input or a collection.
+    pub input_kind: InputKind,
 }
 
 impl TransformDefinition {
-    /// Create a new `TransformDefinition`.
+    /// Create a new `TransformDefinition` with [`InputKind::Single`].
     ///
     /// # Parameters
     ///
@@ -54,13 +60,44 @@ impl TransformDefinition {
             cost,
             quality: quality.clamp(0.0, 1.0),
             label: label.into(),
+            input_kind: InputKind::Single,
+        }
+    }
+
+    /// Create a new `TransformDefinition` with an explicit [`InputKind`].
+    ///
+    /// Use this when registering a collection-based transform (e.g. pages → book).
+    ///
+    /// # Parameters
+    ///
+    /// * `from`       – source [`Format`]
+    /// * `to`         – target [`Format`]
+    /// * `cost`       – relative execution cost (lower is cheaper)
+    /// * `quality`    – expected output quality in the range `[0.0, 1.0]`
+    /// * `label`      – human-readable name identifying the conversion tool or method
+    /// * `input_kind` – whether this definition consumes a single input or a collection
+    pub fn with_input_kind(
+        from: Format,
+        to: Format,
+        cost: f32,
+        quality: f32,
+        label: impl Into<String>,
+        input_kind: InputKind,
+    ) -> Self {
+        Self {
+            from,
+            to,
+            cost,
+            quality: quality.clamp(0.0, 1.0),
+            label: label.into(),
+            input_kind,
         }
     }
 
     /// Convert this definition into a [`TransformEdge`] for use in a
     /// [`TransformGraph`](super::TransformGraph).
     pub fn to_edge(&self) -> TransformEdge {
-        TransformEdge::new(self.from, self.to, self.cost, self.quality)
+        TransformEdge::with_input_kind(self.from, self.to, self.cost, self.quality, self.input_kind)
     }
 }
 
@@ -78,6 +115,7 @@ mod tests {
         assert_eq!(def.cost, 0.5);
         assert!((def.quality - 1.0).abs() < 1e-5);
         assert_eq!(def.label, "pandoc");
+        assert_eq!(def.input_kind, InputKind::Single);
     }
 
     #[test]
@@ -134,6 +172,32 @@ mod tests {
         assert_ne!(a, b);
     }
 
+    // ── with_input_kind ───────────────────────────────────────────────────────
+
+    #[test]
+    fn test_with_input_kind_collection() {
+        let def = TransformDefinition::with_input_kind(
+            Format::Markdown, Format::Epub, 1.0, 0.85, "book-assembler", InputKind::Collection,
+        );
+        assert_eq!(def.input_kind, InputKind::Collection);
+        assert_eq!(def.label, "book-assembler");
+    }
+
+    #[test]
+    fn test_new_defaults_to_single_input_kind() {
+        let def = TransformDefinition::new(Format::Markdown, Format::Html, 0.5, 1.0, "pandoc");
+        assert_eq!(def.input_kind, InputKind::Single);
+    }
+
+    #[test]
+    fn test_definition_inequality_by_input_kind() {
+        let a = TransformDefinition::new(Format::Markdown, Format::Epub, 1.0, 0.85, "tool");
+        let b = TransformDefinition::with_input_kind(
+            Format::Markdown, Format::Epub, 1.0, 0.85, "tool", InputKind::Collection,
+        );
+        assert_ne!(a, b);
+    }
+
     // ── to_edge ───────────────────────────────────────────────────────────────
 
     #[test]
@@ -153,4 +217,20 @@ mod tests {
         let edge = def.to_edge();
         assert!((edge.quality - 1.0).abs() < 1e-5);
     }
+
+    #[test]
+    fn test_to_edge_propagates_input_kind_single() {
+        let def = TransformDefinition::new(Format::Markdown, Format::Html, 0.5, 1.0, "pandoc");
+        let edge = def.to_edge();
+        assert_eq!(edge.input_kind, InputKind::Single);
+    }
+
+    #[test]
+    fn test_to_edge_propagates_input_kind_collection() {
+        let def = TransformDefinition::with_input_kind(
+            Format::Markdown, Format::Epub, 1.0, 0.85, "book-assembler", InputKind::Collection,
+        );
+        let edge = def.to_edge();
+        assert_eq!(edge.input_kind, InputKind::Collection);
+    }
 }

src/graph/input_kind.rs

@@ -0,0 +1,95 @@
+/// Describes how many inputs a transformation consumes.
+///
+/// Most transformations operate on a **single** source document and produce a
+/// single output document.  Some transformations – such as assembling a book
+/// from a collection of pages – consume **multiple** inputs simultaneously and
+/// produce a single aggregated output.
+///
+/// # Example
+///
+/// ```rust
+/// use renderflow::graph::InputKind;
+///
+/// // The default for a standard edge is a single input.
+/// assert_eq!(InputKind::default(), InputKind::Single);
+///
+/// // A collection-based edge aggregates multiple inputs.
+/// let kind = InputKind::Collection;
+/// assert!(kind.is_collection());
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+pub enum InputKind {
+    /// The transformation operates on a single source document.
+    #[default]
+    Single,
+    /// The transformation consumes a collection of source documents and
+    /// produces one aggregated output (e.g. pages → book).
+    Collection,
+}
+
+impl InputKind {
+    /// Return `true` when this is the [`Single`](InputKind::Single) variant.
+    pub fn is_single(self) -> bool {
+        self == InputKind::Single
+    }
+
+    /// Return `true` when this is the [`Collection`](InputKind::Collection) variant.
+    pub fn is_collection(self) -> bool {
+        self == InputKind::Collection
+    }
+}
+
+impl std::fmt::Display for InputKind {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            InputKind::Single => write!(f, "single"),
+            InputKind::Collection => write!(f, "collection"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_default_is_single() {
+        assert_eq!(InputKind::default(), InputKind::Single);
+    }
+
+    #[test]
+    fn test_single_is_single() {
+        assert!(InputKind::Single.is_single());
+        assert!(!InputKind::Single.is_collection());
+    }
+
+    #[test]
+    fn test_collection_is_collection() {
+        assert!(InputKind::Collection.is_collection());
+        assert!(!InputKind::Collection.is_single());
+    }
+
+    #[test]
+    fn test_display_single() {
+        assert_eq!(InputKind::Single.to_string(), "single");
+    }
+
+    #[test]
+    fn test_display_collection() {
+        assert_eq!(InputKind::Collection.to_string(), "collection");
+    }
+
+    #[test]
+    fn test_clone_copy() {
+        let kind = InputKind::Collection;
+        let copied = kind;
+        assert_eq!(kind, copied);
+    }
+
+    #[test]
+    fn test_equality() {
+        assert_eq!(InputKind::Single, InputKind::Single);
+        assert_eq!(InputKind::Collection, InputKind::Collection);
+        assert_ne!(InputKind::Single, InputKind::Collection);
+    }
+}

src/graph/mod.rs

@@ -1,13 +1,15 @@
 mod definition;
 mod definition_registry;
 mod format;
+mod input_kind;
 mod multi_target;
 mod pathfinding;
 mod transform_edge;
 
 pub use definition::TransformDefinition;
 pub use definition_registry::TransformDefinitionRegistry;
 pub use format::Format;
+pub use input_kind::InputKind;
 pub use multi_target::MultiTargetDag;
 pub use pathfinding::TransformPath;
 pub use transform_edge::TransformEdge;
@@ -73,6 +75,17 @@ impl TransformGraph {
         self.graph.add_edge(from_idx, to_idx, edge);
     }
 
+    /// Add a collection-based transformation to the graph.
+    ///
+    /// Equivalent to calling [`add_transform`](Self::add_transform) with a
+    /// [`TransformEdge`] whose [`input_kind`](TransformEdge::input_kind) is
+    /// [`InputKind::Collection`].  Use this for aggregation-style transforms
+    /// where multiple source documents are combined into a single output
+    /// (e.g. pages → book).
+    pub fn add_collection_transform(&mut self, from: Format, to: Format, cost: f32, quality: f32) {
+        self.add_transform(TransformEdge::with_input_kind(from, to, cost, quality, InputKind::Collection));
+    }
+
     /// Return all [`TransformEdge`]s whose source is `from`.
     ///
     /// Returns an empty `Vec` when no outgoing edges exist for the given format.

src/graph/multi_target.rs

@@ -132,12 +132,23 @@ impl MultiTargetDag {
     pub fn node_count(&self) -> usize {
         self.graph.node_count()
     }
+
+    /// Return all edges in the DAG whose [`InputKind`] is [`Collection`](InputKind::Collection).
+    ///
+    /// Collection edges represent aggregation-style transformations that consume
+    /// multiple source documents simultaneously (e.g. pages → book).
+    pub fn collection_edges(&self) -> Vec<&TransformEdge> {
+        self.graph
+            .edge_weights()
+            .filter(|e| e.input_kind.is_collection())
+            .collect()
+    }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::graph::TransformGraph;
+    use crate::graph::{InputKind, TransformGraph};
 
     fn build_graph() -> TransformGraph {
         let mut g = TransformGraph::new();
@@ -324,4 +335,57 @@ mod tests {
 
         assert_eq!(dag.all_edges().len(), dag.edge_count());
     }
+
+    // ── collection_edges ──────────────────────────────────────────────────────
+
+    #[test]
+    fn test_collection_edges_empty_when_no_collection_edges() {
+        let g = build_graph();
+        let dag = g
+            .build_multi_target_dag(Format::Markdown, &[Format::Pdf, Format::Docx])
+            .unwrap();
+
+        assert!(dag.collection_edges().is_empty());
+    }
+
+    #[test]
+    fn test_collection_edges_returns_only_collection_edges() {
+        let mut dag = MultiTargetDag::new();
+        dag.merge_edge(TransformEdge::new(Format::Markdown, Format::Html, 0.5, 1.0));
+        dag.merge_edge(TransformEdge::with_input_kind(
+            Format::Markdown, Format::Epub, 1.0, 0.85, InputKind::Collection,
+        ));
+
+        let collection = dag.collection_edges();
+        assert_eq!(collection.len(), 1);
+        assert_eq!(collection[0].to, Format::Epub);
+        assert_eq!(collection[0].input_kind, InputKind::Collection);
+    }
+
+    #[test]
+    fn test_collection_edges_does_not_include_single_edges() {
+        let mut dag = MultiTargetDag::new();
+        dag.merge_edge(TransformEdge::new(Format::Markdown, Format::Html, 0.5, 1.0));
+        dag.merge_edge(TransformEdge::with_input_kind(
+            Format::Markdown, Format::Epub, 1.0, 0.85, InputKind::Collection,
+        ));
+
+        let collection = dag.collection_edges();
+        assert!(collection.iter().all(|e| e.input_kind.is_collection()));
+    }
+
+    #[test]
+    fn test_collection_edges_multiple() {
+        let mut dag = MultiTargetDag::new();
+        dag.merge_edge(TransformEdge::with_input_kind(
+            Format::Markdown, Format::Epub, 1.0, 0.85, InputKind::Collection,
+        ));
+        dag.merge_edge(TransformEdge::with_input_kind(
+            Format::Html, Format::Pdf, 0.8, 0.85, InputKind::Collection,
+        ));
+        dag.merge_edge(TransformEdge::new(Format::Markdown, Format::Html, 0.5, 1.0));
+
+        let collection = dag.collection_edges();
+        assert_eq!(collection.len(), 2);
+    }
 }