wip: Start adding Mermaid flowcharts for Reactor

Author: jimsynz

.vscode/settings.json

@@ -4,6 +4,7 @@
     "backoff",
     "casted",
     "Desugars",
+    "indentify",
     "lvalue",
     "mappish",
     "noreply",

lib/reactor.ex

@@ -49,6 +49,7 @@ defmodule Reactor do
             undo: []
 
   use Spark.Dsl, default_extensions: [extensions: [Dsl]]
+  @behaviour Reactor.Mermaid.Render
 
   @type context :: %{optional(atom) => any}
   @type context_arg :: Enumerable.t({atom, any})
@@ -219,4 +220,8 @@ defmodule Reactor do
       {:error, reason} -> raise reason
     end
   end
+
+  @doc false
+  def to_mermaid(reactor, options) when is_struct(reactor, __MODULE__),
+    do: Reactor.Mermaid.Render.Reactor.to_mermaid(reactor, options)
 end

lib/reactor/argument.ex

@@ -5,6 +5,8 @@ defmodule Reactor.Argument do
 
   defstruct description: nil, name: nil, source: nil, transform: nil
 
+  @behaviour Reactor.Mermaid.Render
+
   alias Reactor.{Argument, Template}
   import Reactor.Template, only: :macros
 
@@ -219,6 +221,11 @@ defmodule Reactor.Argument do
   defguard has_sub_path(argument)
            when is_list(argument.source.sub_path) and argument.source.sub_path != []
 
+  @doc false
+  @impl true
+  def to_mermaid(argument, options),
+    do: Reactor.Mermaid.Render.Argument.to_mermaid(argument, options)
+
   defp validate_options!(options) when is_list(options),
     do: Spark.Options.validate!(options, @options)
 

lib/reactor/mermaid.ex

@@ -0,0 +1,86 @@
+defmodule Reactor.Mermaid do
+  @moduledoc """
+  Converts Reactors and their related entities into a Mermaid diagram.
+  """
+  @options Spark.Options.new!(
+             expand?: [
+               type: :boolean,
+               required: false,
+               default: false,
+               doc: "Whether or not to expand composed Reactors"
+             ],
+             describe?: [
+               type: :boolean,
+               required: false,
+               default: false,
+               doc: "Whether or not to include descriptions, if available"
+             ],
+             direction: [
+               type: {:in, [:top_to_bottom, :bottom_to_top, :right_to_left, :left_to_right]},
+               required: false,
+               default: :top_to_bottom,
+               doc: "The direction to render the flowchart"
+             ],
+             indent: [
+               type: :non_neg_integer,
+               required: false,
+               default: 0,
+               doc: "How much to indent the resulting mermaid"
+             ]
+           )
+
+  @type options :: unquote(Spark.Options.option_typespec(@options))
+
+  import __MODULE__.Utils
+
+  @doc """
+  Convert the Reactor into Mermaid.
+
+  ## Options
+
+  #{Spark.Options.docs(@options)}
+  """
+  @spec to_mermaid(module | Reactor.t(), options) :: {:ok, iodata()} | {:error, any}
+  def to_mermaid(reactor, options \\ [])
+
+  def to_mermaid(reactor, options) do
+    with {:ok, options} <- Spark.Options.validate(options, @options) do
+      do_to_mermaid(reactor, options)
+    end
+  end
+
+  @doc """
+  Convert the Reactor into Mermaid
+
+  Raising version of `to_mermaid/2`
+  """
+  @spec to_mermaid!(module | Reactor.t(), options) :: iodata | no_return()
+  def to_mermaid!(reactor, options \\ []) do
+    case to_mermaid(reactor, options) do
+      {:ok, iodata} -> iodata
+      {:error, reason} when is_exception(reason) -> raise reason
+      {:error, reason} -> raise RuntimeError, reason
+    end
+  end
+
+  defp do_to_mermaid(reactor, options) when is_atom(reactor) do
+    if Code.ensure_loaded?(reactor) && function_exported?(reactor, :spark_is, 0) &&
+         reactor.spark_is() == Reactor do
+      do_to_mermaid(reactor.reactor(), options)
+    else
+      {:error, ArgumentError.exception(message: "`reactor` argument is not a Reactor")}
+    end
+  end
+
+  defp do_to_mermaid(reactor, options) when is_struct(reactor, Reactor) do
+    with {:ok, reactor} <- Reactor.Planner.plan(reactor) do
+      mermaid = __MODULE__.Render.to_mermaid(reactor, indent(options))
+      {:ok, indentify([["flowchart #{direction(options[:direction])}\n"] | mermaid], options)}
+    end
+  end
+
+  defp direction(:top_to_bottom), do: "TD"
+  defp direction(:bottom_to_top), do: "BT"
+  defp direction(:left_to_right), do: "LR"
+  defp direction(:right_to_left), do: "RL"
+end

lib/reactor/mermaid/render.ex

@@ -0,0 +1,40 @@
+defmodule Reactor.Mermaid.Render do
+  @moduledoc """
+  The behaviour for converting items into [Mermaid](https://mermaid.js.org/) charts.
+
+  Don't call this behaviour directly, instead use it via `Reactor.Mermaid`.
+  """
+
+  @doc """
+  Convert something item into Mermaid
+
+  Options will have previously been validated by `Reactor.Mermaid.to_mermaid/2`.
+  """
+  @callback to_mermaid(module | struct, Reactor.Mermaid.options()) :: iodata() | no_return
+
+  @doc """
+  Convert something item into Mermaid
+
+  Options will have previously been validated by `Reactor.Mermaid.to_mermaid/2`.
+  """
+  @spec to_mermaid(module | struct, Reactor.Mermaid.options()) :: iodata() | no_return
+  def to_mermaid(module, options) when is_atom(module) do
+    if Spark.implements_behaviour?(module, __MODULE__) do
+      module.to_mermaid(module, options)
+    else
+      raise ArgumentError,
+            "module `#{module}` does not implement the `#{inspect(__MODULE__)}` behaviour"
+    end
+  end
+
+  def to_mermaid(struct, options) when is_struct(struct) do
+    module = struct.__struct__
+
+    if Spark.implements_behaviour?(module, __MODULE__) do
+      module.to_mermaid(struct, options)
+    else
+      raise ArgumentError,
+            "module `#{module}` does not implement the `#{inspect(__MODULE__)}` behaviour"
+    end
+  end
+end

lib/reactor/mermaid/render/argument.ex

@@ -0,0 +1,67 @@
+defmodule Reactor.Mermaid.Render.Argument do
+  @moduledoc false
+  import Reactor.Mermaid.Utils
+  alias Reactor.Argument
+  require Argument
+
+  @doc false
+  def to_mermaid(argument, options) when Argument.is_from_value(argument) do
+    target_id =
+      options
+      |> Keyword.fetch!(:parent_step)
+      |> Map.fetch!(:name)
+      |> mermaid_id(:step)
+
+    source_id =
+      argument.source.value
+      |> mermaid_id(:value)
+
+    indentify(
+      """
+      #{source_id}{{"`#{md_escape(inspect(argument.source.value, pretty: true))}`"}}}
+      #{do_argument_link(source_id, target_id, argument, options)}
+      """,
+      options
+    )
+  end
+
+  def to_mermaid(argument, options) when Argument.is_from_input(argument) do
+    target_id =
+      options
+      |> Keyword.fetch!(:parent_step)
+      |> Map.fetch!(:name)
+      |> mermaid_id(:step)
+
+    source_id =
+      argument.source.name
+      |> mermaid_id(:input)
+
+    source_id
+    |> do_argument_link(target_id, argument, options)
+    |> indentify(options)
+  end
+
+  def to_mermaid(argument, options) do
+    target_id =
+      options
+      |> Keyword.fetch!(:parent_step)
+      |> Map.fetch!(:name)
+      |> mermaid_id(:step)
+
+    source_id =
+      argument.source.name
+      |> mermaid_id(:step)
+
+    source_id
+    |> do_argument_link(target_id, argument, options)
+    |> indentify(options)
+  end
+
+  defp do_argument_link(source_id, target_id, argument, options) do
+    if options[:describe?] && is_binary(argument.description) do
+      "#{source_id} -->|#{name(argument.name)} -- #{argument.description}|#{target_id}\n"
+    else
+      "#{source_id} -->|#{name(argument.name)}|#{target_id}\n"
+    end
+  end
+end

lib/reactor/mermaid/render/reactor.ex

@@ -0,0 +1,45 @@
+defmodule Reactor.Mermaid.Render.Reactor do
+  @moduledoc false
+  import Reactor.Mermaid.Utils
+
+  @doc false
+  def to_mermaid(reactor, options) do
+    inputs = emit_inputs(reactor, indent(options))
+    steps = emit_steps(reactor, indent(options))
+
+    [
+      indentify("subgraph #{inspect(reactor.id)}\n", options),
+      inputs,
+      steps,
+      indentify("end", options)
+    ]
+  end
+
+  defp emit_inputs(reactor, options) do
+    Enum.map(reactor.inputs, fn input_name ->
+      emit_input(reactor, input_name, options)
+    end)
+  end
+
+  defp emit_input(reactor, input_name, options) do
+    if options[:describe?] do
+      indentify(
+        [
+          "#{mermaid_id(input_name, :input)}>\"`",
+          "**Input #{input_name}**\n",
+          md_escape(Map.get(reactor.input_descriptions, input_name)),
+          "`\"]\n"
+        ],
+        options
+      )
+    else
+      indentify(["#{mermaid_id(input_name, :input)}>\"Input #{input_name}\"]\n"], options)
+    end
+  end
+
+  defp emit_steps(reactor, options) do
+    reactor.plan
+    |> Graph.vertices()
+    |> Enum.map(&Reactor.Step.to_mermaid(&1, options))
+  end
+end

lib/reactor/mermaid/render/step.ex

@@ -0,0 +1,53 @@
+defmodule Reactor.Mermaid.Render.Step do
+  @moduledoc false
+  import Reactor.Mermaid.Utils
+  alias Reactor.Mermaid.Render
+
+  @doc false
+  def to_mermaid(step, options) do
+    module = impl_for(step)
+    arg_options = Keyword.put(options, :parent_step, step)
+    arguments = Enum.map(step.arguments, &Render.to_mermaid(&1, arg_options))
+
+    step =
+      if Spark.implements_behaviour?(module, Render) do
+        module.to_mermaid(step, options)
+      else
+        default_describe_step(step, module, options)
+      end
+
+    [arguments, step]
+  end
+
+  @doc false
+  def default_describe_step(step, module, options) do
+    if options[:describe?] do
+      indentify(
+        [
+          mermaid_id(step.name, :step),
+          "[\"`**",
+          md_escape("#{name(step.name)}(#{inspect(module)})"),
+          "**\n",
+          md_escape(step.description),
+          "`\"]\n"
+        ],
+        options
+      )
+    else
+      indentify(
+        [
+          mermaid_id(step.name, :step),
+          "[\"",
+          name(step.name),
+          "(",
+          inspect(module),
+          ")\"]\n"
+        ],
+        options
+      )
+    end
+  end
+
+  defp impl_for(%{impl: {module, _}}) when is_atom(module), do: module
+  defp impl_for(%{impl: module}) when is_atom(module), do: module
+end