feat: migration dependency visualization using GraphViz/Mermaid

cot-core/src/error/error_impl.rs

@@ -1,5 +1,6 @@
 use std::error::Error as StdError;
 use std::fmt::Display;
+use std::io;
 use std::ops::Deref;
 
 use derive_more::with_trait::Debug;
@@ -291,6 +292,8 @@ impl From<tower_sessions::session::Error> for Error {
     }
 }
 
+impl_into_cot_error!(io::Error);
+
 #[cfg(test)]
 mod tests {
     use derive_more::with_trait::Debug;
@@ -301,11 +304,11 @@ mod tests {
 
     #[derive(Debug, thiserror::Error)]
     #[error("outer error")]
-    struct OuterError(#[source] std::io::Error);
+    struct OuterError(#[source] io::Error);
 
     #[test]
     fn error_new() {
-        let inner = std::io::Error::other("server error");
+        let inner = io::Error::other("server error");
         let error = Error::wrap(inner);
 
         assert!(StdError::source(&error).is_none());
@@ -314,7 +317,7 @@ mod tests {
 
     #[test]
     fn error_display() {
-        let inner = std::io::Error::other("server error");
+        let inner = io::Error::other("server error");
         let error = Error::internal(inner);
 
         let display = format!("{error}");
@@ -324,7 +327,7 @@ mod tests {
 
     #[test]
     fn error_wrap_and_is_wrapper() {
-        let inner = std::io::Error::other("wrapped");
+        let inner = io::Error::other("wrapped");
         let error = Error::wrap(inner);
 
         assert!(error.is_wrapper());
@@ -375,7 +378,7 @@ mod tests {
 
     #[test]
     fn error_from_template_render() {
-        let askama_err = askama::Error::Custom(Box::new(std::io::Error::other("fail")));
+        let askama_err = askama::Error::Custom(Box::new(io::Error::other("fail")));
         let error: Error = askama_err.into();
 
         assert!(error.to_string().contains("failed to render template"));
@@ -407,10 +410,10 @@ mod tests {
         let err = Error::with_status("root error", StatusCode::BAD_REQUEST);
         assert_snapshot!(format!("{err:?}"), @"root error");
 
-        let err = Error::wrap(std::io::Error::other("io error"));
+        let err = Error::wrap(io::Error::other("io error"));
         assert_snapshot!(format!("{err:?}"), @"io error");
 
-        let io_err = std::io::Error::other("inner io error");
+        let io_err = io::Error::other("inner io error");
         let err = Error::wrap(OuterError(io_err));
         assert_snapshot!(format!("{err:?}"), @r###"
         outer error
@@ -419,7 +422,7 @@ mod tests {
            0: inner io error
         "###);
 
-        let err = Error::internal(OuterError(std::io::Error::other("inner io error")));
+        let err = Error::internal(OuterError(io::Error::other("inner io error")));
         assert_snapshot!(format!("{err:?}"), @r###"
         outer error
 
@@ -438,9 +441,7 @@ mod tests {
         #[error("wrapper error")]
         struct WrapperError(#[source] OuterError);
 
-        let err = Error::internal(WrapperError(OuterError(std::io::Error::other(
-            "inner io error",
-        ))));
+        let err = Error::internal(WrapperError(OuterError(io::Error::other("inner io error"))));
 
         assert_snapshot!(format!("{err:?}"), @"
         wrapper error
@@ -458,7 +459,7 @@ mod tests {
     )]
     fn error_debug_printing_alternate() {
         let err = Error::with_status(
-            OuterError(std::io::Error::other("inner io error")),
+            OuterError(io::Error::other("inner io error")),
             StatusCode::INTERNAL_SERVER_ERROR,
         );
         assert_snapshot!(format!("{err:#?}"), @r#"

cot/src/cli.rs

@@ -8,7 +8,7 @@ use async_trait::async_trait;
 pub use clap;
 use clap::{Arg, ArgAction, ArgMatches, Command, value_parser};
 #[cfg(feature = "db")]
-use cot::db::migrations::{MigrationEngine, SyncDynMigration};
+use cot::db::migrations::{GraphExporter, GraphFormat, MigrationEngine, SyncDynMigration};
 use cot::project::BootstrappedProject;
 use derive_more::Debug;
 
@@ -21,6 +21,7 @@ const LISTEN_PARAM: &str = "listen";
 const COLLECT_STATIC_DIR_PARAM: &str = "dir";
 const MIGRATION_GROUP_SUBCOMMAND: &str = "migration";
 const MIGRATION_ROLLBACK_SUBCOMMAND: &str = "rollback";
+const MIGRATION_GRAPH_SUBCOMMAND: &str = "graph";
 
 /// A central point for configuring the default Command Line Interface (CLI) for
 /// Cot-powered projects.
@@ -101,6 +102,7 @@ impl Cli {
             let mut migration_group =
                 CliTaskGroup::new(MIGRATION_GROUP_SUBCOMMAND).about("Database migration commands");
             migration_group.add_task(MigrationRollback);
+            migration_group.add_task(MigrationGraph);
 
             cli.add_task(migration_group);
         }
@@ -655,6 +657,75 @@ impl CliTask for MigrationRollback {
     }
 }
 
+#[cfg(feature = "db")]
+struct MigrationGraph;
+
+#[cfg(feature = "db")]
+#[async_trait(?Send)]
+impl CliTask for MigrationGraph {
+    fn subcommand(&self) -> Command {
+        Command::new(MIGRATION_GRAPH_SUBCOMMAND)
+            .about("Export the migration dependency graph for visualization")
+            .arg(
+                Arg::new("format")
+                    .long("format")
+                    .value_name("FORMAT")
+                    .value_parser(["dot", "mermaid"])
+                    .default_value("dot")
+                    .help("Output format: dot (Graphviz) or mermaid"),
+            )
+            .arg(
+                Arg::new("output")
+                    .short('o')
+                    .long("output")
+                    .value_name("FILE")
+                    .value_parser(value_parser!(PathBuf))
+                    .required(false)
+                    .help("Write to a file instead of stdout"),
+            )
+    }
+
+    async fn execute(
+        &mut self,
+        matches: &ArgMatches,
+        bootstrapper: Bootstrapper<WithConfig>,
+    ) -> Result<()> {
+        let format = match matches.get_one::<String>("format").map(String::as_str) {
+            Some("mermaid") => GraphFormat::Mermaid,
+            _ => GraphFormat::Dot,
+        };
+
+        let bootstrapper = bootstrapper
+            .with_apps()
+            .with_database()
+            .await?
+            .boot()
+            .await?;
+
+        let BootstrappedProject {
+            context,
+            handler: _,
+            error_handler: _,
+        } = bootstrapper.finish();
+
+        let mut migrations: Vec<Box<SyncDynMigration>> = Vec::new();
+        for app in context.apps() {
+            migrations.extend(app.migrations());
+        }
+
+        let engine = MigrationEngine::new(migrations)?;
+        let exporter = GraphExporter::new(engine.migrations());
+        let rendered = exporter.export(format)?;
+
+        match matches.get_one::<PathBuf>("output") {
+            Some(path) => std::fs::write(path, rendered)?,
+            None => println!("{rendered}"),
+        }
+
+        Ok(())
+    }
+}
+
 /// A macro to generate a [`CliMetadata`] struct from the Cargo manifest.
 #[macro_export]
 macro_rules! metadata {

cot/src/db/migrations.rs

@@ -1,5 +1,6 @@
 //! Database migrations.
 
+mod graph_export;
 mod sorter;
 
 use std::collections::{HashSet, VecDeque};
@@ -9,6 +10,7 @@ use std::io::Write;
 use std::{fmt, io};
 
 pub use cot_macros::migration_op;
+pub(crate) use graph_export::{GraphExporter, GraphFormat};
 use sea_query::{ColumnDef, StringLen};
 use thiserror::Error;
 use tracing::{Level, info};
@@ -486,6 +488,10 @@ impl MigrationEngine {
             .await?;
         Ok(())
     }
+
+    pub(crate) fn migrations(&self) -> &[MigrationWrapper] {
+        &self.migrations
+    }
 }
 
 /// Resolves the possible migration names that can be used to refer to a