Merge pull request #282 from egohygiene/copilot/add-graph-based-cli-execution

feat: Add graph-based CLI execution (--target, --all)

Author: szmyty

src/cli.rs

@@ -45,7 +45,9 @@ pub enum Commands {
             renderflow build --config custom.yaml   Build with a custom config file\n  \
             renderflow build --dry-run              Preview what would be built\n  \
             renderflow build --optimization speed   Build using speed optimization mode\n  \
-            renderflow build --optimization pareto  Build with Pareto-optimal path selection"
+            renderflow build --optimization pareto  Build with Pareto-optimal path selection\n  \
+            renderflow build --target pdf           Build only the PDF output via graph resolution\n  \
+            renderflow build --all                  Build all reachable outputs via graph resolution"
     )]
     Build {
         /// Path to the renderflow configuration file
@@ -62,6 +64,19 @@ pub enum Commands {
         /// pareto (return Pareto-optimal frontier of non-dominated paths).
         #[arg(long, value_name = "MODE")]
         optimization: Option<OptimizationMode>,
+
+        /// Build only the specified output format using graph-based path resolution.
+        /// The format must be reachable from the input format via the configured transforms.
+        /// Requires a 'transforms' key in the config file.
+        /// Cannot be combined with --all.
+        #[arg(long, value_name = "FORMAT", conflicts_with = "all")]
+        target: Option<String>,
+
+        /// Build all reachable output formats using graph-based path resolution.
+        /// Requires a 'transforms' key in the config file.
+        /// Cannot be combined with --target.
+        #[arg(long, conflicts_with = "target")]
+        all: bool,
     },
 
     /// Watch for file changes and automatically rebuild

src/commands/graph_build.rs

@@ -0,0 +1,182 @@
+use std::fs;
+use std::path::Path;
+
+use anyhow::{Context, Result};
+use tracing::info;
+
+use crate::config::load_config_for_graph;
+use crate::files::ensure_output_dir;
+use crate::graph::Format;
+use crate::optimization::OptimizationMode;
+use crate::transforms::yaml_loader::build_graph_and_executor_from_yaml;
+
+/// Run graph-based execution targeting a single output format.
+///
+/// The transform graph is resolved automatically from the `transforms` YAML
+/// file referenced in `config_path`.  The shortest path (according to
+/// `optimization`) from the detected source format to `target` is found,
+/// and every intermediate and final format is produced.
+///
+/// # Errors
+///
+/// Returns an error when:
+/// * the config file cannot be read or parsed,
+/// * no `transforms` key is present in the config,
+/// * `target` is not a recognised format,
+/// * `target` is not reachable from the source format,
+/// * any transform in the execution plan fails.
+pub fn run_target(
+    config_path: &str,
+    target: &str,
+    dry_run: bool,
+    optimization: Option<OptimizationMode>,
+) -> Result<()> {
+    let target_format = target
+        .parse::<Format>()
+        .with_context(|| format!("'{}' is not a valid target format", target))?;
+
+    run_impl(config_path, Some(vec![target_format]), dry_run, optimization)
+}
+
+/// Run graph-based execution targeting all formats reachable from the source.
+///
+/// The transform graph is resolved automatically from the `transforms` YAML
+/// file referenced in `config_path`.  Every format reachable from the source
+/// format is produced in dependency order.
+///
+/// # Errors
+///
+/// Returns an error when:
+/// * the config file cannot be read or parsed,
+/// * no `transforms` key is present in the config,
+/// * no output formats are reachable from the source format,
+/// * any transform in the execution plan fails.
+pub fn run_all(
+    config_path: &str,
+    dry_run: bool,
+    optimization: Option<OptimizationMode>,
+) -> Result<()> {
+    run_impl(config_path, None, dry_run, optimization)
+}
+
+/// Shared implementation for `run_target` and `run_all`.
+///
+/// `explicit_targets` is `Some(vec)` for `--target` mode and `None` for
+/// `--all` mode (targets are discovered dynamically from the graph).
+fn run_impl(
+    config_path: &str,
+    explicit_targets: Option<Vec<Format>>,
+    dry_run: bool,
+    optimization: Option<OptimizationMode>,
+) -> Result<()> {
+    if dry_run {
+        info!("Dry-run mode enabled — no files will be created and no commands will be executed");
+    }
+    info!("Running graph-based build pipeline");
+
+    let config = load_config_for_graph(config_path)?;
+    info!("Loaded config successfully");
+
+    let transforms_path = config.transforms.as_deref().ok_or_else(|| {
+        anyhow::anyhow!(
+            "Graph-based execution requires a 'transforms' key in the config file \
+             pointing to a YAML transform configuration"
+        )
+    })?;
+
+    let (graph, executor) = build_graph_and_executor_from_yaml(transforms_path)?;
+    info!("Loaded transform graph from '{}'", transforms_path);
+
+    let opt_mode = optimization.unwrap_or(config.optimization);
+    info!(optimization = %opt_mode, "Using optimization mode");
+
+    // Derive the source format from the config's input field.
+    let source_format: Format = config
+        .input_format()
+        .to_string()
+        .parse()
+        .with_context(|| {
+            format!(
+                "Could not map input format '{}' to a known graph format",
+                config.input_format()
+            )
+        })?;
+
+    // Determine which formats to build.
+    let targets: Vec<Format> = match explicit_targets {
+        Some(t) => t,
+        None => {
+            // --all: discover every format reachable from the source.
+            let reachable = graph.reachable_from(source_format);
+            if reachable.is_empty() {
+                anyhow::bail!(
+                    "No output formats are reachable from '{}' in the transform graph",
+                    source_format
+                );
+            }
+            info!(
+                "Discovered {} reachable output format(s): {}",
+                reachable.len(),
+                reachable
+                    .iter()
+                    .map(|f| f.to_string())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+            reachable
+        }
+    };
+
+    // Build the minimal DAG that covers all targets.
+    let dag = graph
+        .build_multi_target_dag_with_mode(source_format, &targets, opt_mode)
+        .ok_or_else(|| {
+            anyhow::anyhow!(
+                "Could not build an execution plan: one or more target formats \
+                 are not reachable from '{}' in the transform graph",
+                source_format
+            )
+        })?;
+
+    let input_stem = Path::new(&config.input)
+        .file_stem()
+        .and_then(|s| s.to_str())
+        .unwrap_or("document");
+
+    let output_dir = if dry_run {
+        let path = std::path::PathBuf::from(&config.output_dir);
+        info!(
+            "[DRY RUN] Would create output directory: {}",
+            path.display()
+        );
+        for target in &targets {
+            let output_path = path.join(format!("{}.{}", input_stem, target));
+            info!("[DRY RUN] Would write '{}' output to: {}", target, output_path.display());
+        }
+        return Ok(());
+    } else {
+        ensure_output_dir(&config.output_dir)?
+    };
+
+    // Read and execute.
+    let content = fs::read_to_string(&config.input)
+        .with_context(|| format!("Failed to read input file: {}", config.input))?;
+
+    info!("Executing graph-based pipeline");
+    let results = executor
+        .execute(&dag, source_format, content)
+        .context("Graph execution failed")?;
+
+    // Write each produced format to disk (skip the source format).
+    for (format, output_content) in &results {
+        if *format == source_format {
+            continue;
+        }
+        let output_path = output_dir.join(format!("{}.{}", input_stem, format));
+        fs::write(&output_path, output_content)
+            .with_context(|| format!("Failed to write output to '{}'", output_path.display()))?;
+        info!("✔ Output written to: {}", output_path.display());
+    }
+
+    Ok(())
+}

src/commands/mod.rs

@@ -1,3 +1,4 @@
 pub mod audit;
 pub mod build;
+pub mod graph_build;
 pub mod watch;

src/config.rs

@@ -71,6 +71,7 @@ pub struct OutputConfig {
 
 #[derive(Debug, Deserialize)]
 pub struct Config {
+    #[serde(default)]
     pub outputs: Vec<OutputConfig>,
     pub input: String,
     #[serde(default = "default_output_dir")]
@@ -155,6 +156,19 @@ pub fn load_config(path: &str) -> Result<Config> {
     Ok(config)
 }
 
+/// Load a config file without requiring the `outputs` key to be present.
+///
+/// Unlike [`load_config`], this function skips the full
+/// [`Config::validate`] call.  It is intended for graph-based execution
+/// modes (`--target`, `--all`) where output formats are resolved from the
+/// transform graph rather than from a static `outputs` list.
+pub fn load_config_for_graph(path: &str) -> Result<Config> {
+    let content = fs::read_to_string(path)
+        .with_context(|| format!("Failed to read config file: {}", path))?;
+    serde_yaml_ng::from_str(&content)
+        .with_context(|| format!("Failed to parse YAML config: {}", path))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/graph/mod.rs

@@ -315,6 +315,47 @@ impl TransformGraph {
         Some(dag)
     }
 
+    /// Return all [`Format`] variants reachable from `from` via any sequence
+    /// of directed edges.
+    ///
+    /// The source format itself is excluded from the result.  An empty `Vec`
+    /// is returned when `from` is not a node in the graph or when no outgoing
+    /// edges exist.
+    ///
+    /// # 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));
+    ///
+    /// let reachable = graph.reachable_from(Format::Markdown);
+    /// assert!(reachable.contains(&Format::Html));
+    /// assert!(reachable.contains(&Format::Pdf));
+    /// assert!(!reachable.contains(&Format::Markdown));
+    /// ```
+    pub fn reachable_from(&self, from: Format) -> Vec<Format> {
+        use petgraph::visit::Bfs;
+
+        let Some(&start_idx) = self.nodes.get(&from) else {
+            return Vec::new();
+        };
+
+        let mut bfs = Bfs::new(&self.graph, start_idx);
+        let mut reachable = Vec::new();
+
+        // The first call to `next` returns `start_idx` itself; skip it.
+        bfs.next(&self.graph);
+
+        while let Some(nx) = bfs.next(&self.graph) {
+            reachable.push(self.graph[nx]);
+        }
+
+        reachable
+    }
+
     /// Return the Pareto-optimal frontier of paths from `from` to `to`.
     ///
     /// All simple paths between the two formats are enumerated first.  Any
@@ -891,4 +932,65 @@ mod tests {
         assert_eq!(frontier.len(), 2);
         assert!(frontier[0].total_cost <= frontier[1].total_cost);
     }
+
+    // ── reachable_from ────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_reachable_from_empty_graph_returns_empty() {
+        let graph = TransformGraph::new();
+        assert!(graph.reachable_from(Format::Markdown).is_empty());
+    }
+
+    #[test]
+    fn test_reachable_from_excludes_source() {
+        let mut graph = TransformGraph::new();
+        graph.add_transform(markdown_to_html());
+
+        let reachable = graph.reachable_from(Format::Markdown);
+        assert!(!reachable.contains(&Format::Markdown));
+    }
+
+    #[test]
+    fn test_reachable_from_direct_neighbour() {
+        let mut graph = TransformGraph::new();
+        graph.add_transform(markdown_to_html());
+
+        let reachable = graph.reachable_from(Format::Markdown);
+        assert!(reachable.contains(&Format::Html));
+        assert_eq!(reachable.len(), 1);
+    }
+
+    #[test]
+    fn test_reachable_from_transitive_neighbours() {
+        let mut graph = TransformGraph::new();
+        graph.add_transform(markdown_to_html());
+        graph.add_transform(html_to_pdf());
+
+        let reachable = graph.reachable_from(Format::Markdown);
+        assert!(reachable.contains(&Format::Html));
+        assert!(reachable.contains(&Format::Pdf));
+        assert_eq!(reachable.len(), 2);
+    }
+
+    #[test]
+    fn test_reachable_from_unknown_format_returns_empty() {
+        let mut graph = TransformGraph::new();
+        graph.add_transform(markdown_to_html());
+
+        // Epub is not a node in the graph.
+        assert!(graph.reachable_from(Format::Epub).is_empty());
+    }
+
+    #[test]
+    fn test_reachable_from_disconnected_component_not_included() {
+        let mut graph = TransformGraph::new();
+        graph.add_transform(markdown_to_html());
+        // A disconnected edge: Rst → Latex (not reachable from Markdown).
+        graph.add_transform(TransformEdge::new(Format::Rst, Format::Latex, 1.0, 1.0));
+
+        let reachable = graph.reachable_from(Format::Markdown);
+        assert!(reachable.contains(&Format::Html));
+        assert!(!reachable.contains(&Format::Rst));
+        assert!(!reachable.contains(&Format::Latex));
+    }
 }

src/main.rs

@@ -37,8 +37,14 @@ fn main() -> Result<()> {
         .init();
 
     match cli.command {
-        Some(Commands::Build { config, dry_run, optimization }) => {
-            commands::build::run(&config, dry_run, optimization)?
+        Some(Commands::Build { config, dry_run, optimization, target, all }) => {
+            if let Some(ref target_format) = target {
+                commands::graph_build::run_target(&config, target_format, dry_run, optimization)?
+            } else if all {
+                commands::graph_build::run_all(&config, dry_run, optimization)?
+            } else {
+                commands::build::run(&config, dry_run, optimization)?
+            }
         }
         Some(Commands::Watch { config, debounce }) => commands::watch::run(&config, debounce)?,
         Some(Commands::Audit) => commands::audit::run()?,