alembic 0.1.0

data/app/models/alembic/flow/canvas.rb

@@ -0,0 +1,167 @@
+module Alembic
+  module Flow
+    class Canvas
+      def initialize(document, registry: Flow.registry)
+        @document = document
+        @registry = registry
+      end
+
+      def to_h
+        { "nodes" => nodes, "edges" => edges, "palette" => palette, "violations" => violations }
+      end
+
+      private
+
+      def nodes
+        @document.nodes.map { |node| drawn_step(node) } + waiting.map { |gap| drawn_placeholder(gap) }
+      end
+
+      def drawn_step(node)
+        { "id" => node.id, "type" => node.type, "label" => label_for(node),
+          "config" => node.config, "ports" => [], "ends_here" => ends_here?(node), "begins_here" => begins_here?(node),
+          "loose" => loose?(node), "choices" => choices_for(node), "placeholder" => false, **placed[node.id] }
+      end
+
+      def drawn_placeholder(gap)
+        { "id" => gap[:id], "type" => "placeholder", "label" => gap[:on], "config" => {}, "ports" => [],
+          "ends_here" => false, "begins_here" => false, "loose" => false, "choices" => {},
+          "placeholder" => true, "from" => gap[:from], "on" => gap[:on], **placed[gap[:id]] }
+      end
+
+      def edges
+        drawn.edges.each_with_index.map do |edge, index|
+          { "id" => "#{edge.from}-#{edge.to}-#{index}", "source" => edge.from, "target" => edge.to, "label" => edge.on&.to_s,
+            "placeholder" => waiting.any? { |gap| gap[:id] == edge.to } }.merge(routing(edge, placed))
+        end
+      end
+
+      def placed
+        @placed ||= Layout.new(drawn).positions
+      end
+
+      def drawn
+        @drawn ||= Document.new(@document.to_h.merge(
+          "nodes" => Array(@document.to_h["nodes"]) + waiting.map { |gap| { "id" => gap[:id], "type" => "placeholder" } },
+          "edges" => Array(@document.to_h["edges"]) + waiting.map { |gap| { "from" => gap[:from], "to" => gap[:id], "on" => gap[:on] } }
+        ), registry: @registry)
+      end
+
+      def waiting
+        @waiting ||= @document.nodes.flat_map { |node| gaps_after(node) }
+      end
+
+      def gaps_after(node)
+        wired = @document.edges_from(node.id).map { |edge| edge.on.to_s }
+        results = digest.routing_values(node.id)
+        return [ { id: "#{node.id}--", from: node.id, on: nil } ] if results.empty? && leads_nowhere?(node)
+
+        results.reject { |value| wired.include?(value) }
+          .map { |value| { id: "#{node.id}--#{value}", from: node.id, on: value } }
+      end
+
+      def leads_nowhere?(node)
+        !ends_here?(node) && !loose?(node) && @document.edges_from(node.id).none?
+      end
+
+      def routing(edge, placed)
+        from = placed[edge.from]
+        to = placed[edge.to]
+        return { "leaves" => "bottom", "enters" => "top", "route" => "straight" } unless from && to
+
+        return alongside_routing(from, to) unless to["row"] > from["row"]
+
+        { "leaves" => "bottom", "enters" => "top",
+          "route" => to["column"] == from["column"] ? "straight" : "lane" }
+      end
+
+      def alongside_routing(from, to)
+        leftward = to["column"] < from["column"]
+
+        { "leaves" => leftward ? "left" : "right", "enters" => leftward ? "right" : "left",
+          "route" => to["row"] == from["row"] ? "straight" : "detour" }
+      end
+
+      def palette
+        @registry.step_types.reject(&:begins_here?).map do |step_type|
+          { "type" => step_type.id.to_s, "label" => step_type.step_name,
+            "fields" => step_type.settings.fields.transform_keys(&:to_s).transform_values(&:to_s),
+            "labels" => step_type.settings.labels.transform_keys(&:to_s),
+            "choices" => step_type.settings.choices.transform_keys(&:to_s),
+            "records" => holdings_of(step_type),
+            "record_labels" => step_type.settings.record_labels.to_h { |name, held| [ name.to_s, held.transform_keys(&:to_s) ] },
+            "awaits_input" => step_type.awaits_input? }
+        end
+      end
+
+      def holdings_of(step_type)
+        step_type.settings.record_fields.to_h do |name, holds|
+          [ name.to_s, holds.transform_keys(&:to_s).transform_values(&:to_s) ]
+        end
+      end
+
+      def violations
+        Validator.new(@document, registry: @registry).violations.map do |violation|
+          { "node" => violation.node, "problem" => violation.problem.to_s, "detail" => violation.detail }
+        end
+      end
+
+      def label_for(node)
+        Name.of(node, @registry)
+      end
+
+      def choices_for(node)
+        naming_steps(node).index_with { earlier_than(node) }.merge(drawn_by(node)).merge(named_outputs_by(node))
+      end
+
+      def named_outputs_by(node)
+        step_type_for(node)&.settings&.outputs_of.to_h.to_h do |name, source|
+          [ name.to_s, digest.outputs_of(node.config[source.to_s]) ]
+        end
+      end
+
+      def drawn_by(node)
+        step_type_for(node)&.settings&.drawn_from.to_h.to_h do |name, source|
+          [ name.to_s, digest.values_of(step_named_by(node, source), node.config[source.to_s]) ]
+        end
+      end
+
+      def step_named_by(node, source)
+        node.config[step_type_for(node).settings.outputs_of[source].to_s]
+      end
+
+      def digest
+        Digest.new(@document, registry: @registry)
+      end
+
+      def naming_steps(node)
+        step_type_for(node)&.settings&.naming_steps.to_a.map(&:to_s)
+      end
+
+      def earlier_than(node)
+        digest.preceding(node.id).map do |id|
+          { "value" => id, "label" => label_for(@document.node(id)) }
+        end
+      end
+
+      def ends_here?(node)
+        step_type_for(node)&.ends_here? || false
+      end
+
+      def loose?(node)
+        @document.entry.present? && @document.reachable.exclude?(node.id)
+      end
+
+      def begins_here?(node)
+        step_type_for(node)&.begins_here? || false
+      end
+
+      def ports_for(node)
+        digest.routing_values(node.id)
+      end
+
+      def step_type_for(node)
+        @registry.fetch(node.type) if @registry.registered?(node.type)
+      end
+    end
+  end
+end

data/app/models/alembic/flow/change.rb

@@ -0,0 +1,18 @@
+module Alembic
+  module Flow
+    module Change
+      PHRASING = { "added" => "Added", "updated" => "Updated", "removed" => "Removed",
+                   "moved" => "Moved", "connected" => "Connected", "disconnected" => "Disconnected", "returned" => "Returned to" }.freeze
+
+      def self.phrase(change)
+        named = Array(change["named"]).compact_blank.map { |name| "“#{name}”" }
+        verb = PHRASING.fetch(change["action"], change["action"])
+
+        return "#{verb} #{named.join(' → ')}" if named.any?
+        return "#{verb} #{change['detail']}" if change["detail"].present?
+
+        verb
+      end
+    end
+  end
+end

data/app/models/alembic/flow/condition.rb

@@ -0,0 +1,24 @@
+module Alembic
+  module Flow
+    class Condition
+      include Step
+
+      step_name "Condition"
+
+      setting :step, type: :previous_step
+      setting :output, outputs_of: :step, required: true
+      setting :comparison, type: :select, options: [ "is", "is not" ], required: true
+      setting :answer, from: :output, required: true
+
+      output :result, type: :boolean, values: [ true, false ]
+
+      names_by { |node| node.config.values_at("step", "comparison", "answer").compact_blank.join(" ").presence }
+
+      def route(node, state)
+        matched = state[node.config["step"]] == node.config["answer"]
+
+        node.config["comparison"] == "is not" ? !matched : matched
+      end
+    end
+  end
+end

data/app/models/alembic/flow/definition.rb

@@ -0,0 +1,132 @@
+module Alembic
+  module Flow
+    class Definition < ApplicationRecord
+      self.table_name = "alembic_flows"
+
+      enum :status, { active: "active", hidden: "hidden", inactive: "inactive" }
+      enum :kind, { scored: "scored", guide: "guide" }
+      enum :persists, { unsaved: "unsaved", each_step: "each_step", on_finish: "on_finish" }
+
+      validates :slug, presence: true
+
+      after_initialize :begin_the_flow, if: :new_record?
+
+      scope :listable, -> { active }
+
+      # Declared before :definition_versions so responses clear first, otherwise
+      # destroying a diagnostic trips the responses -> definition_versions FK.
+      has_many :runs, class_name: "Alembic::Flow::Run", foreign_key: :flow_id, dependent: :destroy
+      has_many :definition_versions, class_name: "Alembic::Flow::Version", foreign_key: :flow_id, dependent: :destroy
+      has_many :summary_versions, class_name: "Alembic::Flow::SummaryVersion", foreign_key: :flow_id, dependent: :destroy
+
+      def self.upsert_definition(definition)
+        find_or_initialize_by(slug: definition["slug"]).tap do |diagnostic|
+          diagnostic.save!
+          diagnostic.record_definition(definition) unless diagnostic.definition == definition
+        end
+      end
+
+      def definition
+        current_definition_version&.definition
+      end
+
+      def current_definition_version
+        definition_versions.find_by(number: cursor)
+      end
+
+      def edit_history
+        @edit_history ||= EditHistory.new(self)
+      end
+
+      def summaries
+        @summaries ||= Summaries.new(self)
+      end
+
+      def publish
+        create_version
+
+        publish_version(current_definition_version)
+      end
+
+      def return_to(version)
+        raise ActiveRecord::RecordNotFound unless definition_versions.exists?(version.id)
+        raise OutOfService if version.out_of_service?
+
+        update!(document: version.definition, undone_changes: [],
+          changes_since_version: changes_since_version.to_a + [ returning_to(version) ])
+      end
+
+      def create_version
+        record_definition(document, changes_since_version.to_a) unless versioned?
+
+        update!(undo_history: edit_history.undoable, changes_since_version: [], undone_changes: [])
+      end
+
+      def returning_to(version)
+        { "action" => "returned", "steps" => [], "named" => [],
+          "detail" => "version #{version.number}", "before" => document }
+      end
+
+      def versioned?
+        document == definition
+      end
+
+      def record_definition(payload, captured = [])
+        definition_versions.create!(number: next_definition_number, definition: payload,
+          changes_captured: captured.map { |change| change.except("before") })
+          .tap { |version| update!(definition_cursor: version.number, document: payload) }
+      end
+
+      def publish_version(version)
+        raise OutOfService if version.out_of_service?
+        return if live_version == version
+
+        live_version&.update!(status: :superseded)
+        version.update!(status: :live)
+      end
+
+      def available?
+        !inactive?
+      end
+
+      def retire_version(version)
+        version.update!(status: :retired)
+      end
+
+      def withdraw_version(version)
+        version.update!(status: :withdrawn)
+      end
+
+      def live_version
+        definition_versions.find_by(status: :live)
+      end
+
+      def live_definition
+        live_version&.definition
+      end
+
+      def runner
+        Runner.new(live_definition)
+      end
+
+      private
+
+      def begin_the_flow
+        self.document ||= { "nodes" => [ { "id" => "start", "type" => "start" }, { "id" => "end", "type" => "terminal" } ],
+                            "edges" => [ { "from" => "start", "to" => "end" } ] }
+      end
+
+      def cursor
+        definition_cursor || recorded_numbers.max
+      end
+
+      def recorded_numbers
+        definition_versions.pluck(:number)
+      end
+
+      def next_definition_number
+        (definition_versions.maximum(:number) || 0) + 1
+      end
+    end
+  end
+end

data/app/models/alembic/flow/digest.rb

@@ -0,0 +1,116 @@
+module Alembic
+  module Flow
+    class Digest
+      def initialize(document, registry: Flow.registry)
+        @document = document
+        @registry = registry
+      end
+
+      def entry
+        @document.node(@document.entry)
+      end
+
+      def step(id)
+        @document.node(id)
+      end
+
+      def steps
+        @document.nodes
+      end
+
+      def preceding(id)
+        return [] unless @document.reachable.include?(id)
+
+        @document.nodes.map(&:id).uniq
+          .reject { |other| other == id || @document.reachable(without: other).include?(id) }
+      end
+
+      def routing_values(id)
+        named = step(id)
+        return [] unless named && step_type(named)&.routes?
+
+        step_type(named).outputs.flat_map { |output| values_taken(output, named) }.map { |value| value["value"].to_s }
+      end
+
+      def values_taken(output, node)
+        return output.values_for(node) unless output.from
+
+        values_out_of(node.config[output.from.to_s])
+      end
+
+      def values_of(id, output_name)
+        named = step(id)
+        return [] unless named && output_name.present?
+
+        step_type(named)&.values_of(output_name, named).to_a
+      end
+
+      def outputs_of(id)
+        named = step(id)
+        return [] unless named
+
+        step_type(named)&.outputs.to_a.map { |output| { "value" => output.name.to_s, "label" => output.label } }
+      end
+
+      def values_out_of(id)
+        named = step(id)
+        return [] unless named
+
+        step_type(named)&.outputs.to_a.flat_map { |output| output.values_for(named) }
+      end
+
+      def requirements(id)
+        node = step(id)
+        step_type(node)&.settings&.requirements_for(node.config).to_a
+      end
+
+      def next_step(state)
+        walk(state).last
+      end
+
+      def state_on_path(state)
+        state.slice(*walk(state).first)
+      end
+
+      private
+
+      def walk(state)
+        recorded = []
+        visited = []
+        cursor = entry
+
+        while cursor && !visited.include?(cursor.id)
+          return [ recorded, cursor ] if pending?(cursor, state)
+
+          recorded << cursor.id if state.key?(cursor.id)
+          visited << cursor.id
+          cursor = successor(cursor, state)
+        end
+
+        [ recorded, nil ]
+      end
+
+      def pending?(node, state)
+        return false if state.key?(node.id)
+
+        step_type(node)&.awaits_input? || acts?(node)
+      end
+
+      def acts?(node)
+        step_type(node)&.acts? || false
+      end
+
+      def successor(node, state)
+        leaving = @document.edges_from(node.id)
+        port = step_type(node)&.route(node, state)
+        taken = port.nil? ? leaving.first : leaving.find { |edge| edge.on.to_s == port.to_s }
+
+        taken && @document.node(taken.to)
+      end
+
+      def step_type(node)
+        @registry.fetch(node.type) if node && @registry.registered?(node.type)
+      end
+    end
+  end
+end

data/app/models/alembic/flow/document.rb

@@ -0,0 +1,131 @@
+module Alembic
+  module Flow
+    class Document
+      def initialize(document, registry: Flow.registry)
+        @document = document
+        @registry = registry
+      end
+
+      def nodes
+        Array(@document["nodes"]).map { |node| Node.new(id: node["id"], type: node["type"], config: node.except("id", "type")) }
+      end
+
+      def edges
+        Array(@document["edges"]).map { |edge| Edge.new(from: edge["from"], to: edge["to"], on: edge["on"]) }
+      end
+
+      def entry
+        beginnings.first
+      end
+
+      def beginnings
+        nodes.select { |node| begins_here?(node) }.map(&:id)
+      end
+
+      def begins_here?(node)
+        @registry.registered?(node.type) && @registry.fetch(node.type).begins_here?
+      end
+
+      def node(id)
+        nodes.find { |node| node.id == id }
+      end
+
+      def edges_from(id)
+        edges.select { |edge| edge.from == id }
+      end
+
+      def reachable(without: nil)
+        found = []
+        frontier = [ entry ]
+
+        while (id = frontier.shift)
+          next if found.include?(id) || id == without
+
+          found << id
+          frontier.concat(edges_from(id).map(&:to))
+        end
+
+        found
+      end
+
+      def to_h
+        @document
+      end
+
+      def insert(node, on:, leaving: nil)
+        source, target = on
+        replaced = raw_edges.find { |edge| edge["from"] == source && edge["to"] == target }
+        bridged = [ { "from" => source, "to" => node["id"], "on" => replaced&.fetch("on", nil) }.compact,
+                    { "from" => node["id"], "to" => target, "on" => leaving }.compact ]
+
+        with(nodes: raw_nodes + [ node ], edges: (raw_edges - [ replaced ]) + bridged)
+      end
+
+      def add(node)
+        with(nodes: raw_nodes + [ node ], edges: raw_edges)
+      end
+
+      def connect(from:, to:, on: nil)
+        with(nodes: raw_nodes, edges: raw_edges + [ { "from" => from, "to" => to, "on" => on }.compact ])
+      end
+
+      def disconnect(from:, to:)
+        with(nodes: raw_nodes, edges: raw_edges.reject { |edge| edge["from"] == from && edge["to"] == to })
+      end
+
+      def move(id, on:, leaving: nil)
+        step = raw_nodes.find { |node| node["id"] == id }
+        return self unless step
+
+        remove(id).insert(step, on: on, leaving: leaving)
+      end
+
+      def configure(id, config)
+        reconfigured = raw_nodes.map do |node|
+          node["id"] == id ? node.slice("id", "type").merge(config) : node
+        end
+
+        with(nodes: reconfigured, edges: raw_edges)
+      end
+
+      def rewire(from:, to:, target:)
+        rewritten = raw_edges.map do |edge|
+          edge["from"] == from && edge["to"] == to ? edge.merge("to" => target) : edge
+        end
+
+        with(nodes: raw_nodes, edges: rewritten)
+      end
+
+      def remove(id)
+        incoming = raw_edges.select { |edge| edge["to"] == id }
+        outgoing = raw_edges.select { |edge| edge["from"] == id }
+
+        with(nodes: raw_nodes.reject { |node| node["id"] == id },
+             edges: (raw_edges - incoming - outgoing) + bridges(incoming, outgoing))
+      end
+
+      private
+
+      def bridges(incoming, outgoing)
+        incoming.product(outgoing).map do |arriving, leaving|
+          { "from" => arriving["from"], "to" => leaving["to"], "on" => arriving["on"] }.compact
+        end
+      end
+
+      def raw_nodes
+        Array(@document["nodes"])
+      end
+
+      def raw_edges
+        Array(@document["edges"])
+      end
+
+      def with(nodes:, edges:)
+        Document.new(@document.merge("nodes" => nodes, "edges" => edges), registry: @registry).tap do |edited|
+          broken = Validator.new(edited, registry: @registry).malformations
+          raise InvalidEdit, broken.map { |violation| "#{violation.node}: #{violation.problem}" }.join(", ") if broken.any?
+        end
+      end
+    end
+  end
+end

data/app/models/alembic/flow/drawing.rb

@@ -0,0 +1,15 @@
+module Alembic
+  module Flow
+    module Drawing
+      def self.of(node, registry = Flow.registry)
+        named(node, registry).presence || Flow.drawing
+      end
+
+      def self.named(node, registry)
+        return unless node && registry.registered?(node.type)
+
+        registry.fetch(node.type).drawn_by
+      end
+    end
+  end
+end

data/app/models/alembic/flow/edge.rb

@@ -0,0 +1,9 @@
+module Alembic
+  module Flow
+    Edge = Data.define(:from, :to, :on) do
+      def initialize(from:, to:, on: nil)
+        super
+      end
+    end
+  end
+end

data/app/models/alembic/flow/edit_history.rb

@@ -0,0 +1,75 @@
+module Alembic
+  module Flow
+    class EditHistory
+      def initialize(flow)
+        @flow = flow
+      end
+
+      def undoable?
+        undoable.any?
+      end
+
+      def redoable?
+        undone.any?
+      end
+
+      def undoable
+        @flow.undo_history.to_a + @flow.changes_since_version.to_a
+      end
+
+      def undo_change
+        undone_change = undoable.last
+        return unless undone_change
+
+        @flow.update!(document: undone_change["before"],
+          undone_changes: undone + [ undone_change.merge("after" => @flow.document) ],
+          undo_history: @flow.undo_history.to_a[0...-1],
+          changes_since_version: @flow.changes_since_version.to_a[0...-1])
+      end
+
+      def redo_change
+        redone = undone.last
+        return unless redone
+
+        @flow.update!(document: redone["after"], undone_changes: undone[0...-1],
+          changes_since_version: @flow.changes_since_version.to_a + [ redone.except("after") ])
+      end
+
+      def record(edited, action, steps, before)
+        @flow.update!(document: edited.to_h, undone_changes: [],
+          changes_since_version: with(edited, action, steps, before))
+      end
+
+      def edit_document(payload)
+        @flow.update!(document: payload, undone_changes: [],
+          changes_since_version: @flow.changes_since_version.to_a + [ edited_by_hand ])
+      end
+
+      private
+
+      def with(edited, action, steps, before)
+        return @flow.changes_since_version.to_a unless action
+
+        @flow.changes_since_version.to_a +
+          [ { "action" => action.to_s, "steps" => steps.map(&:to_s),
+              "named" => steps.map { |id| named(edited, id) }, "before" => before } ]
+      end
+
+      def named(edited, id)
+        Name.of(edited.node(id.to_s) || document.node(id.to_s))
+      end
+
+      def document
+        Document.new(@flow.document || @flow.definition || {})
+      end
+
+      def undone
+        @flow.undone_changes.to_a
+      end
+
+      def edited_by_hand
+        { "action" => "edited", "steps" => [], "named" => [ "the definition" ], "before" => @flow.document }
+      end
+    end
+  end
+end