alembic 0.1.0

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

@@ -0,0 +1,44 @@
+module Alembic
+  module Flow
+    class Summaries
+      def initialize(flow)
+        @flow = flow
+      end
+
+      def document
+        current_version&.summary
+      end
+
+      def current_version
+        @flow.summary_versions.find_by(number: cursor)
+      end
+
+      def record(payload)
+        @flow.summary_versions.create!(number: next_number, summary: payload)
+          .tap { |version| @flow.update!(summary_cursor: version.number) }
+      end
+
+      def any?
+        document.present?
+      end
+
+      def of(state)
+        Summary::Report.new(document).results(Summary::Run.new(state: state, steps: steps_by_id))
+      end
+
+      private
+
+      def steps_by_id
+        Array(@flow.definition.to_h["nodes"]).index_by { |node| node["id"] }
+      end
+
+      def cursor
+        @flow.summary_cursor || @flow.summary_versions.pluck(:number).max
+      end
+
+      def next_number
+        (@flow.summary_versions.maximum(:number) || 0) + 1
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Alembic
+  module Flow
+    class SummaryVersion < ApplicationRecord
+      self.table_name = "alembic_flow_summaries"
+
+      belongs_to :flow, class_name: "Alembic::Flow::Definition"
+
+      validates :number, uniqueness: { scope: :flow_id }
+
+      before_update { raise ActiveRecord::ReadOnlyRecord }
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Alembic
+  module Flow
+    class Switch
+      include Step
+
+      step_name "Switch"
+
+      setting :step, type: :previous_step
+
+      output :choice, type: :string, label: "Choice", from: :step
+
+      def route(node, state)
+        state[node.config["step"]]
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,171 @@
+module Alembic
+  module Flow
+    class Validator
+      OPTIONAL = { unrouted_value: :unrouted_values, unfollowed_path: :unfollowed_paths, dead_end: :dead_ends }.freeze
+
+      def initialize(document, registry: Flow.registry, checks: Flow.checks)
+        @document = document
+        @registry = registry
+        @checks = checks
+      end
+
+      def violations
+        structural_violations + unmet_requirements + missing_settings + missing_values + beginnings + asked_for
+      end
+
+      def structural_violations
+        malformations + unreachable
+      end
+
+      def malformations
+        missing_edge_targets + missing_edge_sources + duplicate_ids + no_beginning
+      end
+
+      private
+
+      def asked_for
+        @checks.flat_map { |name| send(OPTIONAL.fetch(name)) }
+      end
+
+      def missing_edge_targets
+        @document.edges.reject { |edge| known?(edge.to) }
+          .map { |edge| Violation.new(node: edge.from, problem: :missing_edge_target, detail: edge.to) }
+      end
+
+      def missing_edge_sources
+        @document.edges.reject { |edge| known?(edge.from) }
+          .map { |edge| Violation.new(node: edge.to, problem: :missing_edge_source, detail: edge.from) }
+      end
+
+      def duplicate_ids
+        @document.nodes.map(&:id).tally.select { |_id, count| count > 1 }
+          .map { |id, _count| Violation.new(node: id, problem: :duplicate_id) }
+      end
+
+      def no_beginning
+        return [] if known?(@document.entry)
+
+        [ Violation.new(node: nil, problem: :no_beginning) ]
+      end
+
+      def unmet_requirements
+        @document.nodes.flat_map do |node|
+          requirements_for(node).reject { |required| precedes_every_path?(required, node.id) }
+            .map { |required| Violation.new(node: node.id, problem: :unmet_requirement, detail: required) }
+        end
+      end
+
+      def dead_ends
+        @document.nodes.filter_map { |node| ending_problem(node) }
+      end
+
+      def ending_problem(node)
+        leaving = @document.edges_from(node.id).any?
+        return Violation.new(node: node.id, problem: :past_the_end) if ends_here?(node) && leaving
+        return if ends_here?(node) || leaving
+
+        Violation.new(node: node.id, problem: :dead_end)
+      end
+
+      def ends_here?(node)
+        @registry.registered?(node.type) && @registry.fetch(node.type).ends_here?
+      end
+
+      def unfollowed_paths
+        @document.nodes.select { |node| leads_on?(node) }.flat_map { |node| unfollowed_paths_from(node) }
+      end
+
+      def leads_on?(node)
+        @registry.registered?(node.type) && !@registry.fetch(node.type).routes?
+      end
+
+      def unfollowed_paths_from(node)
+        @document.edges_from(node.id).drop(1)
+          .map { |edge| Violation.new(node: node.id, problem: :unfollowed_path, detail: edge.to) }
+      end
+
+      def unrouted_values
+        @document.nodes.flat_map { |node| unrouted_values_in(node) }
+      end
+
+      def unrouted_values_in(node)
+        wired = @document.edges_from(node.id).map { |edge| edge.on.to_s }
+
+        digest.routing_values(node.id).reject { |value| wired.include?(value) }
+          .map { |value| Violation.new(node: node.id, problem: :unrouted_value, detail: value) }
+      end
+
+      def digest
+        Digest.new(@document, registry: @registry)
+      end
+
+      def beginnings
+        @document.beginnings.drop(1).map { |id| Violation.new(node: id, problem: :many_beginnings) } + led_into
+      end
+
+      def led_into
+        @document.beginnings.select { |id| @document.edges.any? { |edge| edge.to == id } }
+          .map { |id| Violation.new(node: id, problem: :before_the_beginning) }
+      end
+
+      def missing_values
+        @document.nodes.flat_map { |node| missing_values_in(node) }
+      end
+
+      def missing_values_in(node)
+        drawn_of(node).filter_map do |name, source|
+          chosen = node.config[name.to_s]
+          next if chosen.blank? || node.config[source.to_s].blank?
+          next if offered_to(node, source).include?(chosen.to_s)
+
+          Violation.new(node: node.id, problem: :missing_value, detail: chosen.to_s)
+        end
+      end
+
+      def offered_to(node, source)
+        naming = @registry.fetch(node.type).settings.outputs_of[source]
+
+        digest.values_of(node.config[naming.to_s], node.config[source.to_s]).map { |value| value["value"].to_s }
+      end
+
+      def drawn_of(node)
+        return {} unless @registry.registered?(node.type)
+
+        @registry.fetch(node.type).settings.drawn_from
+      end
+
+      def missing_settings
+        @document.nodes.flat_map do |node|
+          required_of(node).reject { |name| node.config[name.to_s].present? }
+            .map { |name| Violation.new(node: node.id, problem: :missing_setting, detail: name.to_s) }
+        end
+      end
+
+      def required_of(node)
+        return [] unless @registry.registered?(node.type)
+
+        @registry.fetch(node.type).settings.required
+      end
+
+      def requirements_for(node)
+        return [] unless @registry.registered?(node.type)
+
+        @registry.fetch(node.type).settings.requirements_for(node.config)
+      end
+
+      def precedes_every_path?(required, id)
+        known?(required) && !@document.reachable(without: required).include?(id)
+      end
+
+      def unreachable
+        return [] unless known?(@document.entry)
+
+        (@document.nodes.map(&:id).uniq - @document.reachable).map { |id| Violation.new(node: id, problem: :unreachable) }
+      end
+
+      def known?(id)
+        @document.node(id).present?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Alembic
+  module Flow
+    class Version < ApplicationRecord
+      self.table_name = "alembic_flow_versions"
+
+      enum :status, { draft: "draft", live: "live", superseded: "superseded",
+                      retired: "retired", withdrawn: "withdrawn" }
+
+      belongs_to :flow, class_name: "Alembic::Flow::Definition"
+
+      validates :number, uniqueness: { scope: :flow_id }
+
+      def out_of_service?
+        retired? || withdrawn?
+      end
+
+      def changes
+        changes_captured.to_a
+      end
+
+      FROZEN = %w[definition number flow_id changes_captured].freeze
+
+      before_update { raise ActiveRecord::ReadOnlyRecord if changed.intersect?(FROZEN) }
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+module Alembic
+  module Flow
+    Violation = Data.define(:node, :problem, :detail) do
+      def initialize(node:, problem:, detail: nil)
+        super
+      end
+    end
+  end
+end

data/app/models/alembic/flow.rb

@@ -0,0 +1,44 @@
+module Alembic
+  module Flow
+    FIELD_TYPES = %i[string integer float boolean select multi_select previous_step from_step list].freeze
+
+    OUTPUT_TYPES = %i[string integer float boolean].freeze
+    OPTIONAL_CHECKS = %i[unrouted_value unfollowed_path dead_end].freeze
+
+    class UnknownFieldType < ArgumentError; end
+    class UnknownOutputType < ArgumentError; end
+    class UnknownStepType < KeyError; end
+    class UnknownCheck < ArgumentError; end
+    class InvalidEdit < StandardError; end
+
+    DRAWING = "alembic/flow/steps/choosing".freeze
+
+    class << self
+      def draws_with(template)
+        @drawing = template
+      end
+
+      def drawing
+        @drawing.presence || DRAWING
+      end
+
+      def step(id, &declaration)
+        registry.register(StepType.define(id, &declaration))
+      end
+
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def check(name)
+        raise UnknownCheck, "#{name} is not one of #{OPTIONAL_CHECKS.join(', ')}" unless OPTIONAL_CHECKS.include?(name)
+
+        checks << name unless checks.include?(name)
+      end
+
+      def checks
+        @checks ||= []
+      end
+    end
+  end
+end

data/app/models/alembic/outputs/band.rb

@@ -0,0 +1,22 @@
+module Alembic
+  module Outputs
+    module Band
+      def self.output_type
+        Summary::OutputType.define(:band) do
+          label "Band"
+          compute { |config, _run, so_far| Band.covering(config, so_far[config["of"]]) }
+        end
+      end
+
+      def self.register(registry = Summary.registry)
+        registry.register(output_type)
+      end
+
+      def self.covering(config, number)
+        ordered = Array(config["bands"]).sort_by { |band| band["ceiling"] || Float::INFINITY }
+
+        ordered.find { |band| band["ceiling"].nil? || number < band["ceiling"] }&.fetch("name", nil)
+      end
+    end
+  end
+end

data/app/models/alembic/outputs/grouped.rb

@@ -0,0 +1,26 @@
+module Alembic
+  module Outputs
+    module Grouped
+      def self.output_type
+        Summary::OutputType.define(:grouped) do
+          label "By area"
+          compute { |config, run, _so_far| Grouped.shares(run, config["by"].presence) }
+        end
+      end
+
+      def self.register(registry = Summary.registry)
+        registry.register(output_type)
+      end
+
+      def self.bucket(step, marker)
+        marker ? step[marker] : Steps::Question.category_of(step)
+      end
+
+      def self.shares(run, marker)
+        run.state.keys.group_by { |id| Grouped.bucket(run.step(id), marker) }
+          .except(nil)
+          .transform_values { |ids| Percentage.of(run, ids) }
+      end
+    end
+  end
+end

data/app/models/alembic/outputs/lowest.rb

@@ -0,0 +1,20 @@
+module Alembic
+  module Outputs
+    module Lowest
+      def self.output_type
+        Summary::OutputType.define(:lowest) do
+          label "Weakest"
+          compute { |config, _run, so_far| Lowest.of(so_far[config["of"]], config["count"]) }
+        end
+      end
+
+      def self.register(registry = Summary.registry)
+        registry.register(output_type)
+      end
+
+      def self.of(shares, count)
+        shares.to_h.sort_by { |_name, share| share }.first(count.presence&.to_i || 1).map(&:first)
+      end
+    end
+  end
+end

data/app/models/alembic/outputs/percentage.rb

@@ -0,0 +1,31 @@
+module Alembic
+  module Outputs
+    module Percentage
+      def self.output_type
+        Summary::OutputType.define(:percentage) do
+          label "Share"
+          compute { |_config, run, _so_far| Percentage.of(run, run.state.keys) }
+        end
+      end
+
+      def self.register(registry = Summary.registry)
+        registry.register(output_type)
+      end
+
+      def self.of(run, ids)
+        offered = ids.sum { |id| most(run.step(id)) }
+        return 0 if offered.zero?
+
+        (captured(run, ids).to_f / offered * 100).round
+      end
+
+      def self.captured(run, ids)
+        ids.sum { |id| WeightedSum.weight_of(run.step(id), run.state[id]) }
+      end
+
+      def self.most(step)
+        Steps::Question.answers_of(step).filter_map { |option| option["weight"].to_i if option.is_a?(Hash) }.max.to_i
+      end
+    end
+  end
+end

data/app/models/alembic/outputs/tally.rb

@@ -0,0 +1,23 @@
+module Alembic
+  module Outputs
+    module Tally
+      def self.output_type
+        Summary::OutputType.define(:tally) do
+          label "How many"
+          compute { |config, run, _so_far| Tally.counted(run, config["tag"], config["by"].presence) }
+        end
+      end
+
+      def self.register(registry = Summary.registry)
+        registry.register(output_type)
+      end
+
+      def self.counted(run, tag, marker)
+        answered = run.state.keys
+        return answered.size if tag.blank?
+
+        answered.count { |id| Grouped.bucket(run.step(id), marker) == tag }
+      end
+    end
+  end
+end

data/app/models/alembic/outputs/weighted_sum.rb

@@ -0,0 +1,26 @@
+module Alembic
+  module Outputs
+    module WeightedSum
+      def self.output_type
+        Summary::OutputType.define(:weighted_sum) do
+          label "Score"
+          compute { |_config, run, _so_far| WeightedSum.total(run) }
+        end
+      end
+
+      def self.register(registry = Summary.registry)
+        registry.register(output_type)
+      end
+
+      def self.total(run)
+        run.state.sum { |id, value| weight_of(run.step(id), value) }
+      end
+
+      def self.weight_of(step, value)
+        chosen = Steps::Question.answers_of(step).find { |option| option.is_a?(Hash) && option["value"] == value }
+
+        chosen&.fetch("weight", nil).to_i
+      end
+    end
+  end
+end

data/app/models/alembic/page.rb

@@ -0,0 +1,11 @@
+require "ks_blocks/layout"
+
+module Alembic
+  class Page < ApplicationRecord
+    include KsBlocks::Layout
+
+    block_layout :blocks, kind: :pages
+
+    validates :name, presence: true
+  end
+end

data/app/models/alembic/runner.rb

@@ -0,0 +1,13 @@
+module Alembic
+  class Runner < Flow::Runner
+    def question_text(id)
+      Steps::Question.asked(step(id)&.config)
+    end
+
+    def choice_label(id, value)
+      chosen = Steps::Question.choices_in(step(id)).find { |choice| choice.value == value }
+
+      chosen&.label.presence || value
+    end
+  end
+end

data/app/models/alembic/steps/question.rb

@@ -0,0 +1,52 @@
+module Alembic
+  module Steps
+    class Question
+      include Flow::Step
+
+      step_name "Question"
+
+      setting :question, type: :string
+      setting :category, type: :string
+      setting :answers, type: :list, required: true do
+        setting :value, type: :string
+        setting :label, type: :string
+        setting :weight, type: :integer
+      end
+
+      output :answer, type: :string, label: "Answer", values: ->(node) { Question.offered(node.config) }
+
+      names_by :question
+      awaits_input
+
+      displays_by { |node| Asked.new(id: node.id.to_sym, text: asked(node.config), choices: choices_in(node)) }
+
+      def self.asked(step)
+        step.to_h["question"] || step.to_h["text"]
+      end
+
+      def self.answers_of(step)
+        Array(step.to_h["answers"] || step.to_h["options"])
+      end
+
+      def self.offered(step)
+        answers_of(step).map do |answer|
+          { "value" => answer["value"], "label" => answer["label"].presence || answer["value"] }
+        end
+      end
+
+      def self.choices_in(node)
+        answers_of(node.config).map { |answer| choice_from(answer) }
+      end
+
+      def self.choice_from(answer)
+        return Choice.new(value: answer) unless answer.is_a?(Hash)
+
+        Choice.new(value: answer["value"], label: answer["label"], hint: answer["hint"])
+      end
+
+      def self.category_of(step)
+        step.to_h["category"] || step.to_h["tag"]
+      end
+    end
+  end
+end

data/app/models/alembic/summary/output_type.rb

@@ -0,0 +1,40 @@
+module Alembic
+  module Summary
+    class OutputType
+      def self.define(id, &declaration)
+        Declaration.new(id).tap { |decl| decl.instance_eval(&declaration) }.to_output_type
+      end
+
+      attr_reader :id, :label
+
+      def initialize(id:, label:, computation:)
+        @id = id
+        @label = label
+        @computation = computation
+      end
+
+      def compute(config, state, so_far)
+        @computation&.call(config, state, so_far)
+      end
+
+      class Declaration
+        def initialize(id)
+          @id = id
+          @label = id.to_s
+        end
+
+        def label(value)
+          @label = value
+        end
+
+        def compute(&computation)
+          @computation = computation
+        end
+
+        def to_output_type
+          OutputType.new(id: @id, label: @label, computation: @computation)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Alembic
+  module Summary
+    class Registry
+      def initialize
+        @output_types = {}
+      end
+
+      def register(output_type)
+        @output_types[output_type.id.to_sym] = output_type
+      end
+
+      def fetch(id)
+        @output_types.fetch(id.to_sym) { raise UnknownOutputType, "no output type registered as #{id}" }
+      end
+
+      def registered?(id)
+        id.present? && @output_types.key?(id.to_sym)
+      end
+
+      def output_types
+        @output_types.values
+      end
+    end
+  end
+end

data/app/models/alembic/summary/report.rb

@@ -0,0 +1,31 @@
+module Alembic
+  module Summary
+    class Report
+      def initialize(configuration, registry: Summary.registry)
+        @configuration = configuration.to_h
+        @registry = registry
+      end
+
+      def results(run)
+        produced = {}
+
+        outputs.map do |output|
+          output_type = @registry.fetch(output["type"])
+          produced[output["id"]] = output_type.compute(output, run, produced)
+
+          Result.new(id: output["id"], label: label_for(output, output_type), value: produced[output["id"]])
+        end
+      end
+
+      private
+
+      def outputs
+        Array(@configuration["outputs"])
+      end
+
+      def label_for(output, output_type)
+        output["label"].presence || output_type.label
+      end
+    end
+  end
+end

data/app/models/alembic/summary/result.rb

@@ -0,0 +1,5 @@
+module Alembic
+  module Summary
+    Result = Data.define(:id, :label, :value)
+  end
+end