alembic 0.1.0

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

@@ -0,0 +1,88 @@
+module Alembic
+  module Flow
+    class Layout
+      SPREAD = 2
+
+      def initialize(document)
+        @document = document
+      end
+
+      def positions
+        rows = depths
+        columns = columns_for(rows)
+
+        rows.to_h { |id, row| [ id, { "row" => row, "column" => columns[id] } ] }
+      end
+
+      private
+
+      def depths
+        walked = walk_from_entry
+
+        walked.merge(stranded(walked).index_with(next_row(walked)))
+      end
+
+      def walk_from_entry
+        seen = {}
+        frontier = starting_points.map { |id| [ id, 0 ] }
+
+        until frontier.empty?
+          id, depth = frontier.shift
+          next if seen.key?(id)
+
+          seen[id] = depth
+          @document.edges_from(id).each { |edge| frontier << [ edge.to, depth + 1 ] if known?(edge.to) }
+        end
+
+        seen
+      end
+
+      def starting_points
+        return [ @document.entry ] if known?(@document.entry)
+
+        arrived = @document.edges.map(&:to)
+        @document.nodes.map(&:id).reject { |id| arrived.include?(id) }
+      end
+
+      def columns_for(rows)
+        @columns = {}
+        @next_leaf = 0
+        rows.keys.each { |id| place(id, branches(rows)) }
+        @columns
+      end
+
+      def branches(rows)
+        claimed = {}
+
+        rows.keys.to_h do |id|
+          mine = @document.edges_from(id).map(&:to).uniq
+            .select { |child| rows[child] == rows[id] + 1 && !claimed.key?(child) }
+          mine.each { |child| claimed[child] = true }
+          [ id, mine ]
+        end
+      end
+
+      def place(id, branches)
+        return @columns[id] if @columns.key?(id)
+
+        mine = branches[id].to_a
+        return @columns[id] = (@next_leaf += SPREAD) - SPREAD if mine.empty?
+
+        spans = mine.map { |child| place(child, branches) }
+        @columns[id] = (spans.min + spans.max) / 2
+      end
+
+      def stranded(walked)
+        @document.nodes.map(&:id).uniq - walked.keys
+      end
+
+      def next_row(walked)
+        (walked.values.max || -1) + 1
+      end
+
+      def known?(id)
+        @document.node(id).present?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Alembic
+  module Flow
+    module Name
+      def self.of(node, registry = Flow.registry)
+        return "" unless node
+
+        named(node, registry) || node.id
+      end
+
+      def self.named(node, registry)
+        registry.fetch(node.type).name_of(node) if registry.registered?(node.type)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+module Alembic
+  module Flow
+    Node = Data.define(:id, :type, :config)
+  end
+end

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

@@ -0,0 +1,23 @@
+module Alembic
+  module Flow
+    Output = Data.define(:name, :label, :type, :values, :from) do
+      def initialize(name:, label: nil, type: :string, values: nil, from: nil)
+        raise UnknownOutputType, "#{type} is not one of #{OUTPUT_TYPES.join(', ')}" unless OUTPUT_TYPES.include?(type)
+
+        super(name: name, label: label.presence || name.to_s.humanize, type: type, values: values, from: from)
+      end
+
+      def values_for(node)
+        Array(values.respond_to?(:call) ? values.call(node) : values).map { |value| taken(value) }
+      end
+
+      private
+
+      def taken(value)
+        return value if value.is_a?(Hash)
+
+        { "value" => value, "label" => value.to_s }
+      end
+    end
+  end
+end

data/app/models/alembic/flow/progress/kept.rb

@@ -0,0 +1,38 @@
+module Alembic
+  module Flow
+    module Progress
+      class Kept
+        def initialize(run)
+          @run = run
+        end
+
+        def definition
+          @run.pinned_definition
+        end
+
+        def summary_of(state)
+          return [] if @run.pinned_summary.blank?
+
+          Summary::Report.new(@run.pinned_summary)
+            .results(Summary::Run.new(state: state, steps: @run.pinned_steps))
+        end
+
+        def recorded
+          @run.recorded
+        end
+
+        def record(id, value)
+          @run.record(id.to_sym, value)
+        end
+
+        def finish(_state)
+          @run
+        end
+
+        def discard_last
+          @run.discard_last
+        end
+      end
+    end
+  end
+end

data/app/models/alembic/flow/progress/loose.rb

@@ -0,0 +1,43 @@
+module Alembic
+  module Flow
+    module Progress
+      class Loose
+        def initialize(flow, answers, definition = nil)
+          @flow = flow
+          @answers = answers.to_h.symbolize_keys
+          @definition = definition
+        end
+
+        def definition
+          @definition || @flow.live_definition
+        end
+
+        def summary_of(state)
+          return [] unless @flow.summaries.any?
+
+          @flow.summaries.of(state)
+        end
+
+        def recorded
+          @answers
+        end
+
+        def record(id, value)
+          @answers = @answers.merge(id.to_sym => value)
+        end
+
+        def finish(state)
+          return unless @flow.on_finish?
+
+          Run.start(@flow).tap { |run| run.update!(recorded: state) }
+        end
+
+        def discard_last
+          last = Runner.new(@flow.live_definition).state_on_path(@answers).keys.last
+
+          @answers = @answers.except(last) if last
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Alembic
+  module Flow
+    module Progress
+      def self.for(flow, run: nil, answers: {}, definition: nil)
+        return Kept.new(run) if run
+
+        Loose.new(flow, answers, definition)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Alembic
+  module Flow
+    class Registry
+      def initialize
+        @step_types = {}
+      end
+
+      def register(step_type)
+        @step_types[step_type.id.to_sym] = step_type
+      end
+
+      def fetch(id)
+        @step_types.fetch(id.to_sym) { raise UnknownStepType, "no step type registered as #{id}" }
+      end
+
+      def registered?(id)
+        id.present? && @step_types.key?(id.to_sym)
+      end
+
+      def step_types
+        @step_types.values
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Alembic
+  module Flow
+    class Run < ApplicationRecord
+      self.table_name = "alembic_flow_runs"
+
+      belongs_to :flow, class_name: "Alembic::Flow::Definition"
+      belongs_to :definition_version, class_name: "Alembic::Flow::Version"
+      belongs_to :summary_version, class_name: "Alembic::Flow::SummaryVersion", optional: true
+      belongs_to :owner, polymorphic: true, optional: true
+
+      def self.start(flow)
+        create!(flow: flow, definition_version: flow.live_version,
+          summary_version: flow.summaries.current_version)
+      end
+
+      def record(step_id, value)
+        update!(recorded: recorded.merge(step_id => value))
+      end
+
+      def recorded
+        super.to_h.symbolize_keys
+      end
+
+      def pinned_definition
+        definition_version.definition.to_h
+      end
+
+      def pinned_summary
+        summary_version&.summary.to_h
+      end
+
+      def next_step(state)
+        digest.next_step(state.transform_keys(&:to_s))
+      end
+
+      def walked(state)
+        digest.state_on_path(state.transform_keys(&:to_s))
+      end
+
+      def digest
+        @digest ||= Digest.new(Document.new(pinned_definition))
+      end
+
+      def discard_last
+        last = walked(recorded).keys.map(&:to_sym).last
+        update!(recorded: recorded.except(last)) if last
+      end
+
+      def pinned_steps
+        Array(definition_version.definition.to_h["nodes"]).index_by { |node| node["id"] }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Alembic
+  module Flow
+    class Runner
+      def initialize(document, registry: Flow.registry)
+        @document = document.to_h
+        @registry = registry
+        @digest = Digest.new(Document.new(@document, registry: registry), registry: registry)
+      end
+
+      def slug
+        @document["slug"]
+      end
+
+      def headline
+        @document["headline"]
+      end
+
+      def steps
+        @digest.steps
+      end
+
+      def step(id)
+        @digest.step(id.to_s)
+      end
+
+      def next_step(state)
+        shown(@digest.next_step(named(state)))
+      end
+
+      def run(progress)
+        while (node = @digest.next_step(named(progress.recorded))) && acts?(node)
+          progress.record(node.id, @registry.fetch(node.type).process(node, named(progress.recorded)))
+        end
+      end
+
+      def drawing_at(state)
+        Drawing.of(@digest.next_step(named(state)), @registry)
+      end
+
+      def state_on_path(state)
+        @digest.state_on_path(named(state)).symbolize_keys
+      end
+
+      def steps_on_path(state)
+        state_on_path(state).keys.map { |id| shown(@digest.step(id.to_s)) }
+      end
+
+      private
+
+      def acts?(node)
+        @registry.registered?(node.type) && @registry.fetch(node.type).acts?
+      end
+
+      def shown(node)
+        return node unless node && @registry.registered?(node.type)
+
+        @registry.fetch(node.type).display_of(node) || node
+      end
+
+      def named(state)
+        state.transform_keys(&:to_s)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+module Alembic
+  module Flow
+    class Settings
+      attr_reader :fields, :labels, :record_fields, :record_labels, :choices, :drawn_from, :outputs_of
+
+      def initialize(fields: {}, labels: {}, record_fields: {}, record_labels: {}, choices: {},
+        limits: {}, checks: {}, required: [], drawn_from: {}, outputs_of: {})
+        @fields = fields
+        @labels = labels
+        @record_fields = record_fields
+        @record_labels = record_labels
+        @choices = choices
+        @limits = limits
+        @checks = checks
+        @required = required
+        @drawn_from = drawn_from
+        @outputs_of = outputs_of
+      end
+
+      def naming_steps
+        fields.select { |_name, type| type == :previous_step }.keys
+      end
+
+      def required
+        fields.keys.select { |name| @required.include?(name) || naming_steps.include?(name) }
+      end
+
+      def requirements_for(config)
+        naming_steps.map { |name| config.to_h[name.to_s] }.compact_blank
+      end
+
+      def coerce(config)
+        config.to_h.to_h { |name, value| [ name, cast(fields[name.to_sym], value, record_fields[name.to_sym]) ] }
+      end
+
+      def objections(config)
+        config.to_h.flat_map { |name, value| objections_to(name.to_sym, value) }.compact
+      end
+
+      private
+
+      def objections_to(name, value)
+        [ unoffered(name, value), over_limit(name, value), refused(name, value) ]
+      end
+
+      def unoffered(name, value)
+        offered = choices[name]
+        return unless offered
+
+        stray = Array(value).find { |chosen| offered.exclude?(chosen) }
+        "#{labels[name]} does not offer #{stray}" if stray
+      end
+
+      def over_limit(name, value)
+        allowed = @limits[name]
+        return unless allowed && Array(value).size > allowed
+
+        "#{labels[name]} takes at most #{allowed}"
+      end
+
+      def refused(name, value)
+        @checks[name]&.call(value)
+      end
+
+      def cast(type, value, holds = nil)
+        case type
+        when :integer then Integer(value, exception: false)
+        when :float then Float(value, exception: false)
+        when :boolean then ActiveModel::Type::Boolean.new.cast(value).present?
+        when :list then Array(value).map { |entry| cast_entry(entry, holds.to_h) }
+        else value
+        end
+      end
+
+      def cast_entry(entry, holds)
+        entry.to_h.to_h { |name, value| [ name, cast(holds[name.to_sym], value) ] }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Alembic
+  module Flow
+    class Start
+      include Step
+
+      step_name "Start"
+
+      begins_here
+
+      names_by { |_node| "Start" }
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module Alembic
+  module Flow
+    module Step
+      extend ActiveSupport::Concern
+
+      WORDS = (StepType::Declaration.public_instance_methods(false) - [ :to_step_type ]).freeze
+      BEHAVIOURS = %i[route process].freeze
+
+      included do
+        class_attribute :declarations, default: []
+      end
+
+      class_methods do
+        WORDS.each do |word|
+          define_method(word) do |*arguments, **options, &block|
+            self.declarations += [ [ word, arguments, options, block ] ]
+          end
+        end
+
+        def step_type
+          spoken = declarations + behaviours
+          StepType.define(step_type_id) do
+            spoken.each { |word, arguments, options, block| public_send(word, *arguments, **options, &block) }
+          end
+        end
+
+        def behaviours
+          BEHAVIOURS.select { |word| method_defined?(word) }
+            .map { |word| [ word, [], {}, ->(node, state) { new.public_send(word, node, state) } ] }
+        end
+
+        def register(registry = Flow.registry)
+          registry.register(step_type)
+        end
+
+        def step_type_id
+          name.demodulize.underscore.to_sym
+        end
+      end
+    end
+  end
+end

data/app/models/alembic/flow/step_type/declaration.rb

@@ -0,0 +1,118 @@
+module Alembic
+  module Flow
+    class StepType
+      class Declaration
+        def initialize(id)
+          @id = id
+          @step_name = id.to_s
+          @fields = {}
+          @labels = {}
+          @record_fields = {}
+          @record_labels = {}
+          @choices = {}
+          @limits = {}
+          @checks = {}
+          @drawn_from = {}
+          @outputs_of = {}
+          @declared_outputs = []
+          @required = []
+          @awaits_input = false
+          @ends_here = false
+          @begins_here = false
+        end
+
+        def output(name, type: :string, label: nil, values: nil, from: nil)
+          @declared_outputs += [ Output.new(name: name, type: type, label: label, values: values, from: from) ]
+        end
+
+        def displays_by(&display)
+          @display = display
+        end
+
+        def drawn_by(template)
+          @drawn_by = template
+        end
+
+        def process(&behaviour)
+          @behaviour = behaviour
+        end
+
+        def route(&routing)
+          @routing = routing
+        end
+
+        def step_name(value)
+          @step_name = value
+        end
+
+        def awaits_input
+          @awaits_input = true
+        end
+
+        def ends_here
+          @ends_here = true
+        end
+
+        def begins_here
+          @begins_here = true
+        end
+
+        def names_by(field = nil, &naming)
+          @naming_field = field
+          @naming = naming
+        end
+
+        def setting(name, type: nil, from: nil, outputs_of: nil, label: nil, options: nil, limit: nil, check: nil, required: false, &entries)
+          type ||= :from_step if from
+          type ||= :from_step if outputs_of
+          raise UnknownFieldType, "#{type} is not one of #{FIELD_TYPES.join(', ')}" unless FIELD_TYPES.include?(type)
+
+          @drawn_from[name] = from if from
+          @outputs_of[name] = outputs_of if outputs_of
+          @required += [ name ] if required
+
+          declare_entries(name, entries) if type == :list
+          declare_choices(name, type, options)
+          @limits[name] = limit if limit
+          @checks[name] = check if check
+          @labels[name] = label.presence || name.to_s.humanize
+          @fields[name] = type
+        end
+
+        protected
+
+        attr_reader :fields, :labels
+
+        private
+
+        def declare_choices(name, type, options)
+          return @choices[name] = options if options.present?
+          raise UnknownFieldType, "a #{type} must offer options" if %i[select multi_select].include?(type)
+        end
+
+        def declare_entries(name, entries)
+          raise UnknownFieldType, "a list must say what an entry holds" if entries.nil?
+
+          declared = Declaration.new(:entry).tap { |entry| entry.instance_eval(&entries) }
+          @record_fields[name] = declared.fields
+          @record_labels[name] = declared.labels
+        end
+
+        public
+
+        def to_step_type
+          StepType.new(id: @id, step_name: @step_name, settings: settings, awaits_input: @awaits_input,
+            ends_here: @ends_here, begins_here: @begins_here, behaviour: @behaviour, routing: @routing,
+            display: @display, drawn_by: @drawn_by, naming_field: @naming_field, naming: @naming,
+            outputs: @declared_outputs)
+        end
+
+        def settings
+          Settings.new(fields: @fields, labels: @labels, record_fields: @record_fields,
+            record_labels: @record_labels, choices: @choices, limits: @limits, checks: @checks,
+            required: @required, drawn_from: @drawn_from, outputs_of: @outputs_of)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module Alembic
+  module Flow
+    class StepType
+      def self.define(id, &declaration)
+        Declaration.new(id).tap { |decl| decl.instance_eval(&declaration) }.to_step_type
+      end
+
+      attr_reader :id, :step_name, :settings, :naming_field, :naming, :outputs, :drawn_by
+
+      def initialize(id:, step_name:, settings:, awaits_input:, behaviour:, routing:,
+        ends_here: false, begins_here: false, display: nil, drawn_by: nil,
+        naming_field: nil, naming: nil, outputs: [])
+        @id = id
+        @step_name = step_name
+        @settings = settings
+        @awaits_input = awaits_input
+        @ends_here = ends_here
+        @begins_here = begins_here
+        @behaviour = behaviour
+        @routing = routing
+        @display = display
+        @drawn_by = drawn_by
+        @naming_field = naming_field
+        @naming = naming
+        @outputs = outputs
+      end
+
+      def display_of(node)
+        @display&.call(node)
+      end
+
+      def process(node, state)
+        @behaviour&.call(node, state)
+      end
+
+      def route(node, state)
+        @routing&.call(node, state)
+      end
+
+      def name_of(node)
+        @naming&.call(node).presence || node.config[naming_field.to_s].presence
+      end
+
+      def acts?
+        @behaviour.present?
+      end
+
+      def routes?
+        @routing.present?
+      end
+
+      def values_of(name, node)
+        outputs.find { |output| output.name.to_s == name.to_s }&.values_for(node).to_a
+      end
+
+      def awaits_input?
+        @awaits_input
+      end
+
+      def ends_here?
+        @ends_here
+      end
+
+      def begins_here?
+        @begins_here
+      end
+    end
+  end
+end