Stingray.StateMachine.GraphGen 1.0.1

StateMachine Graph Generator

A command-line tool that analyzes C# code using the Stingray.StateMachine library and generates visual graph representations in Mermaid format.

Features

• 🔍 Roslyn-powered analysis: Uses Microsoft.CodeAnalysis to parse C# syntax trees
• 📊 Mermaid diagrams: Generates clean, embeddable state machine diagrams
• 🎨 Visual styling: Initial states highlighted in green, terminal states in pink
• 🚀 Easy to use: Simple command-line interface

Installation

You can install the tool as a local .NET tool after building the solution:

cd Libraries/Stingray.StateMachine
dotnet pack
dotnet tool install --global --add-source ./src/Stingray.StateMachine.GraphGen/bin/Debug/ Stingray.StateMachine.GraphGen

Usage

stingray-statemachine-gen --source /path/to/statemachine/code --output diagram.mmd

Or run directly from source:

dotnet run --project src/Stingray.StateMachine.GraphGen -- \
  --source /path/to/statemachine/code \
  --output diagram.mmd

Options

• --source, -s (required): Directory containing state machine code
• --output, -o (optional): Output file path (default: statemachine-graph.mmd)

Example

# Analyze the example state machine
dotnet run --project src/Stingray.StateMachine.GraphGen -- \
  -s src/Stingray.StateMachine.GraphGen/Example \
  -o example-graph.mmd

How It Works

The tool analyzes C# code and extracts:

1. States: Classes implementing IState<TContext>

   • Uses Class Name as state identifier
   • Detects terminal states (those calling StateResult.Complete())

2. Transitions: Calls to StateResult.TransitionTo<TargetState>()

   • Analyzes Execute() method bodies
   • Builds transition graph

3. Initial State: Detected from SetInitialState() calls

Output Format

The tool generates Mermaid state diagrams:

stateDiagram-v2
    [*] --> SelectUnit
    SelectUnit --> MoveUnit
    MoveUnit --> TakeAction
    TakeAction --> SelectUnit
    SelectUnit --> EnemyTurn
    EnemyTurn --> CheckVictory
    CheckVictory --> SelectUnit

Rendering the Diagram

Option 1: GitHub/Markdown

Embed the .mmd file content directly in markdown:

```mermaid
stateDiagram-v2
    [*] --> SelectUnit
    ...
```

Option 2: Mermaid CLI

Generate PNG/SVG images:

# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# Render to PNG
mmdc -i diagram.mmd -o diagram.png

# Render to SVG
mmdc -i diagram.mmd -o diagram.svg

Option 3: Online Editor

Copy the .mmd content to mermaid.live for interactive preview.

Requirements

• .NET 8.0+
• State machine code using IState<TContext> interface from Stingray.StateMachine

Supported Patterns

The analyzer recognizes:

✅ Class-based state identifiers:

public class MyState : IState<Context> { ... }

✅ Simple transitions:

return StateResult<T>.TransitionTo<NextState>();

✅ Terminal states:

return StateResult<T>.Complete();

✅ Fluent configuration:

new StateMachine<T>()
    .AddState(new MyState())
    .SetInitialState<MyState>();

Limitations

• Does not analyze conditional logic (e.g., if statements determine which transition)
• Best suited for clearly defined state transitions
• Requires generic type arguments for transitions

License

MIT