feat: add introspection and visualization support with Mermaid/JSON export (#5)

seuros · web-flow · commit 241664836815 · 2026-01-17T20:20:04.000+01:00
diff --git a/Cargo.toml b/Cargo.toml
@@ -3,6 +3,7 @@ members = [
     "state-machines",
     "state-machines-core",
     "state-machines-macro",
+    "state-machines-cli",
     "examples/no_std_flight",
     "examples/basic_transitions",
     "examples/guards_and_validation",
diff --git a/examples/async_patterns/Cargo.toml b/examples/async_patterns/Cargo.toml
@@ -7,3 +7,7 @@ publish = false
 [dependencies]
 state-machines = { path = "../../state-machines" }
 pollster = "0.4"
+
+[features]
+default = []
+inspect = ["state-machines/inspect"]
diff --git a/examples/basic_transitions/Cargo.toml b/examples/basic_transitions/Cargo.toml
@@ -5,4 +5,8 @@ edition = "2024"
 publish = false
 
 [dependencies]
-state-machines = { path = "../../state-machines" }
+state-machines = { path = "../../state-machines", features = ["std"] }
+
+[features]
+default = ["inspect"]
+inspect = ["state-machines/inspect"]
diff --git a/examples/basic_transitions/src/main.rs b/examples/basic_transitions/src/main.rs
@@ -127,6 +127,21 @@ state_machine! {
 fn main() {
     println!("=== Airlock Pressure Cycle Demo ===\n");
 
+    // Demonstrate introspection capabilities
+    #[cfg(feature = "inspect")]
+    {
+        let schema = Airlock::<(), Pressurized>::schema();
+        println!("=== Machine Introspection ===\n");
+        println!("Machine: {}", schema.name);
+        println!("Initial State: {}", schema.initial);
+        println!("States: {:?}", schema.states);
+        println!("\nMermaid Diagram:");
+        println!("{}", schema.to_mermaid());
+        println!("JSON Schema:");
+        println!("{}", schema.to_json_pretty());
+        println!();
+    }
+
     // Create new airlock in Pressurized state
     // Type: Airlock<(), Pressurized>
     let airlock = Airlock::new(());
diff --git a/examples/callbacks_lifecycle/Cargo.toml b/examples/callbacks_lifecycle/Cargo.toml
@@ -6,3 +6,7 @@ publish = false
 
 [dependencies]
 state-machines = { path = "../../state-machines" }
+
+[features]
+default = []
+inspect = ["state-machines/inspect"]
diff --git a/examples/dynamic_dispatch_when/Cargo.toml b/examples/dynamic_dispatch_when/Cargo.toml
@@ -6,3 +6,7 @@ publish = false
 
 [dependencies]
 state-machines = { path = "../../state-machines", features = ["dynamic"] }
+
+[features]
+default = []
+inspect = ["state-machines/inspect"]
diff --git a/examples/guards_and_validation/Cargo.toml b/examples/guards_and_validation/Cargo.toml
@@ -6,3 +6,7 @@ publish = false
 
 [dependencies]
 state-machines = { path = "../../state-machines" }
+
+[features]
+default = []
+inspect = ["state-machines/inspect"]
diff --git a/examples/hierarchical_thinking/Cargo.toml b/examples/hierarchical_thinking/Cargo.toml
@@ -5,4 +5,8 @@ edition = "2024"
 publish = false
 
 [dependencies]
-state-machines = { path = "../../state-machines" }
+state-machines = { path = "../../state-machines", features = ["std"] }
+
+[features]
+default = ["inspect"]
+inspect = ["state-machines/inspect"]
diff --git a/examples/hierarchical_thinking/src/main.rs b/examples/hierarchical_thinking/src/main.rs
@@ -265,6 +265,26 @@ fn main() {
     println!("=== Life Support System Hierarchy Demo ===\n");
     println!("This example demonstrates hierarchical states (superstates).\n");
 
+    // Demonstrate introspection with hierarchical states
+    #[cfg(feature = "inspect")]
+    {
+        let schema = LifeSupportSystem::<(), Offline>::schema();
+        println!("=== Machine Introspection (with Superstates) ===\n");
+        println!("Machine: {}", schema.name);
+        println!("States: {:?}", schema.states);
+        if !schema.superstates.is_empty() {
+            println!("Superstates:");
+            for ss in &schema.superstates {
+                println!(
+                    "  {} (initial: {}, descendants: {:?})",
+                    ss.name, ss.initial, ss.descendants
+                );
+            }
+        }
+        println!("\nMermaid Diagram:");
+        println!("{}", schema.to_mermaid());
+    }
+
     // Scenario 1: Activating life support and cycling through modes
     println!("--- Scenario 1: Normal Operations ---");
 
diff --git a/examples/no_std_flight/Cargo.toml b/examples/no_std_flight/Cargo.toml
@@ -6,3 +6,7 @@ publish = false
 
 [dependencies]
 state-machines = { path = "../../state-machines", default-features = false }
+
+[features]
+default = []
+inspect = ["state-machines/inspect"]
diff --git a/state-machines-cli/Cargo.toml b/state-machines-cli/Cargo.toml
@@ -0,0 +1,20 @@
+[package]
+name = "state-machines-cli"
+version = "0.1.0"
+edition = "2024"
+authors = ["Abdelkader Boudih <terminale@gmail.com>"]
+description = "CLI tool for state-machines visualization and introspection"
+license = "MIT"
+repository = "https://github.com/state-machines/state-machines-rs"
+keywords = ["state-machine", "cli", "mermaid", "visualization"]
+categories = ["command-line-utilities", "development-tools"]
+publish = false
+
+[[bin]]
+name = "state-machines"
+path = "src/main.rs"
+
+[dependencies]
+state-machines-core = { version = "0.7.0", path = "../state-machines-core", features = ["std"] }
+clap = { version = "4", features = ["derive"] }
+serde_json = "1.0"
diff --git a/state-machines-cli/src/main.rs b/state-machines-cli/src/main.rs
@@ -0,0 +1,171 @@
+//! CLI tool for state-machines visualization and introspection.
+//!
+//! # Usage
+//!
+//! Convert JSON schema to Mermaid:
+//! ```bash
+//! echo '{"name":"Door","initial":"Closed",...}' | state-machines render mermaid
+//! ```
+//!
+//! Validate JSON schema:
+//! ```bash
+//! cat schema.json | state-machines validate
+//! ```
+//!
+//! Format JSON schema:
+//! ```bash
+//! cat schema.json | state-machines render json
+//! ```
+
+use clap::{Parser, Subcommand};
+use state_machines_core::schema::MachineSchema;
+use std::io::{self, Read};
+
+#[derive(Parser)]
+#[command(name = "state-machines")]
+#[command(about = "CLI tool for state-machines visualization and introspection")]
+#[command(version)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Render a state machine schema to various formats
+    Render {
+        /// Output format: mermaid, json
+        #[arg(value_name = "FORMAT")]
+        format: String,
+
+        /// Input JSON file (reads from stdin if not provided)
+        #[arg(short, long)]
+        input: Option<String>,
+    },
+
+    /// Validate a state machine schema
+    Validate {
+        /// Input JSON file (reads from stdin if not provided)
+        #[arg(short, long)]
+        input: Option<String>,
+    },
+
+    /// Show example schema
+    Example,
+}
+
+fn read_input(input: Option<String>) -> io::Result<String> {
+    match input {
+        Some(path) => std::fs::read_to_string(path),
+        None => {
+            let mut buffer = String::new();
+            io::stdin().read_to_string(&mut buffer)?;
+            Ok(buffer)
+        }
+    }
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::Render { format, input } => {
+            let json = read_input(input)?;
+            let schema: MachineSchema = serde_json::from_str(&json)?;
+
+            match format.as_str() {
+                "mermaid" => {
+                    println!("{}", schema.to_mermaid());
+                }
+                "json" => {
+                    println!("{}", schema.to_json_pretty());
+                }
+                other => {
+                    eprintln!("Unknown format: {}. Supported: mermaid, json", other);
+                    std::process::exit(1);
+                }
+            }
+        }
+
+        Commands::Validate { input } => {
+            let json = read_input(input)?;
+            match serde_json::from_str::<MachineSchema>(&json) {
+                Ok(schema) => {
+                    println!("✓ Valid schema: {}", schema.name);
+                    println!("  States: {}", schema.states.len());
+                    println!("  Events: {}", schema.events.len());
+                    if !schema.superstates.is_empty() {
+                        println!("  Superstates: {}", schema.superstates.len());
+                    }
+                }
+                Err(e) => {
+                    eprintln!("✗ Invalid schema: {}", e);
+                    std::process::exit(1);
+                }
+            }
+        }
+
+        Commands::Example => {
+            let example = MachineSchema {
+                name: "Door".into(),
+                initial: "Closed".into(),
+                states: vec!["Open".into(), "Closed".into(), "Locked".into()],
+                superstates: vec![],
+                events: vec![
+                    state_machines_core::schema::EventSchema {
+                        name: "open".into(),
+                        transitions: vec![state_machines_core::schema::TransitionSchema {
+                            sources: vec!["Closed".into()],
+                            target: "Open".into(),
+                            guards: vec![],
+                            unless: vec![],
+                        }],
+                        guards: vec![],
+                        payload: None,
+                    },
+                    state_machines_core::schema::EventSchema {
+                        name: "close".into(),
+                        transitions: vec![state_machines_core::schema::TransitionSchema {
+                            sources: vec!["Open".into()],
+                            target: "Closed".into(),
+                            guards: vec![],
+                            unless: vec![],
+                        }],
+                        guards: vec![],
+                        payload: None,
+                    },
+                    state_machines_core::schema::EventSchema {
+                        name: "lock".into(),
+                        transitions: vec![state_machines_core::schema::TransitionSchema {
+                            sources: vec!["Closed".into()],
+                            target: "Locked".into(),
+                            guards: vec![],
+                            unless: vec![],
+                        }],
+                        guards: vec![],
+                        payload: None,
+                    },
+                    state_machines_core::schema::EventSchema {
+                        name: "unlock".into(),
+                        transitions: vec![state_machines_core::schema::TransitionSchema {
+                            sources: vec!["Locked".into()],
+                            target: "Closed".into(),
+                            guards: vec![],
+                            unless: vec![],
+                        }],
+                        guards: vec![],
+                        payload: None,
+                    },
+                ],
+                async_mode: false,
+            };
+
+            println!("Example JSON Schema:");
+            println!("{}", example.to_json_pretty());
+            println!("\nExample Mermaid Output:");
+            println!("{}", example.to_mermaid());
+        }
+    }
+
+    Ok(())
+}
diff --git a/state-machines-core/Cargo.toml b/state-machines-core/Cargo.toml
@@ -13,7 +13,11 @@ categories = ["rust-patterns", "no-std"]
 include = ["src/**/*", "Cargo.toml", "../README.md", "LICENSE-MIT", "LICENSE-APACHE"]
 
 [dependencies]
+serde = { version = "1.0", default-features = false, features = ["derive", "alloc"], optional = true }
+serde_json = { version = "1.0", optional = true }
 
 [features]
 default = []
 typestate = []
+inspect = ["serde"]
+std = ["inspect", "serde_json"]
diff --git a/state-machines-core/src/lib.rs b/state-machines-core/src/lib.rs
@@ -2,6 +2,12 @@
 
 use core::fmt::Debug;
 
+#[cfg(feature = "inspect")]
+pub mod schema;
+
+#[cfg(feature = "inspect")]
+pub use schema::{EventSchema, Inspectable, MachineSchema, SuperstateSchema, TransitionSchema};
+
 /// Marker trait for states used by the generated state machines.
 pub trait MachineState: Copy + Eq + Debug + Send + Sync + 'static {}
 
diff --git a/state-machines-core/src/schema.rs b/state-machines-core/src/schema.rs
diff --git a/state-machines-macro/src/codegen.rs b/state-machines-macro/src/codegen.rs
diff --git a/state-machines-macro/src/codegen/inspect.rs b/state-machines-macro/src/codegen/inspect.rs
diff --git a/state-machines/Cargo.toml b/state-machines/Cargo.toml
diff --git a/state-machines/src/lib.rs b/state-machines/src/lib.rs
