alembic 0.1.0 → 0.3.0

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

@@ -1,13 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,118 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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

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

@@ -1,17 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,171 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,44 +0,0 @@
-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/runner.rb

@@ -1,13 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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/views/alembic/flow/steps/_choosing.html.erb

@@ -1,9 +0,0 @@
-<fieldset>
-  <legend class="mb-5 text-xl font-semibold leading-snug text-gray-900"><%= step.text %></legend>
-
-  <div class="space-y-3">
-    <% step.choices.each do |choice| %>
-      <%= ui_radio_card(name: "answers[#{step.id}]", value: choice.value, label: choice.label.presence || choice.value, hint: choice.hint) %>
-    <% end %>
-  </div>
-</fieldset>

data/app/views/alembic/flows/step.html.erb

@@ -1,27 +0,0 @@
-<% content_for(:title, @guide.headline) %>
-
-<%= ui_page(max_width: :md) do %>
-  <%= link_to "← Start over", flow_start_path(@guide.slug), class: "text-sm text-accent-600 hover:text-accent-700" %>
-
-  <div class="mt-6 mb-6">
-    <%= ui_progress(value: @answers.size, max: [ @guide.steps_on_path(@answers).size, 1 ].max, label: "Question #{@answers.size + 1}") %>
-  </div>
-
-  <%= form_with url: step_form[:url], method: step_form[:method], data: { turbo: false } do %>
-    <% if carries_answers? %>
-      <% @answers.each do |key, value| %>
-        <%= hidden_field_tag "answers[#{key}]", value %>
-      <% end %>
-    <% end %>
-
-    <%= render @drawing, step: @question %>
-
-    <div class="mt-8 flex items-center gap-4">
-      <%= ui_button(label: "Next", type: :submit) %>
-
-      <% if @answers.any? %>
-        <button type="submit" name="back" value="1" formnovalidate class="cursor-pointer text-sm text-gray-500 underline underline-offset-2 hover:text-gray-900">← Back</button>
-      <% end %>
-    </div>
-  <% end %>
-<% end %>

data/app/views/alembic/manage/definitions/edit.html.erb

@@ -1,13 +0,0 @@
-<%= ui_page(max_width: :lg) do %>
-  <p class="mb-4">
-    <%= link_to "← Back to the flow", alembic.manage_flow_path(@diagnostic), class: "text-sm text-accent-600 hover:text-accent-700" %>
-  </p>
-
-  <%= ui_form_page(title: "Definition", back_url: alembic.manage_flow_path(@diagnostic), subtitle: @diagnostic.slug) %>
-
-  <%= ui_form(action: alembic.manage_flow_definition_path(@diagnostic), method: :patch) do %>
-    <%= ui_textarea(name: "definition", value: JSON.pretty_generate(@diagnostic.document), rows: 30) %>
-
-    <%= ui_button(label: "Save", type: :submit) %>
-  <% end %>
-<% end %>

data/app/views/alembic/manage/flows/index.html.erb

@@ -1,32 +0,0 @@
-<%= ui_page(max_width: :xl) do %>
-  <%= ui_page_header(title: "Flows", subtitle: "Build and edit your flows") %>
-
-  <%= ui_data_table(
-    items: @diagnostics,
-    columns: [ { title: "Title" }, { slug: "Slug" }, { kind: "Kind" }, { status: "Status" } ],
-    empty_message: "No diagnostics yet."
-  ) do |table| %>
-    <% table.link(:title) { |diagnostic| alembic.manage_flow_path(diagnostic) } %>
-    <% table.actions do |diagnostic| %>
-      <%= ui_form(action: alembic.manage_flow_path(diagnostic), method: :delete) do %>
-        <%= ui_button(label: "Remove", type: :submit, variant: :secondary) %>
-      <% end %>
-    <% end %>
-  <% end %>
-
-  <%= ui_section(title: "Create a diagnostic") do %>
-    <% if @diagnostic&.errors&.any? %>
-      <%= ui_alert(message: @diagnostic.errors.full_messages.to_sentence, type: :error) %>
-    <% end %>
-
-    <%= ui_form(action: alembic.manage_flows_path, method: :post) do %>
-      <label class="block text-sm font-medium mb-1">Slug</label>
-      <%= ui_input(name: "flow[slug]", placeholder: "e.g. business-scorecard") %>
-
-      <label class="block text-sm font-medium mb-1 mt-4">Kind</label>
-      <%= ui_select(name: "flow[kind]", options: [ [ "Scored", "scored" ], [ "Guide", "guide" ] ]) %>
-
-      <%= ui_button(label: "Create", type: :submit, variant: :secondary) %>
-    <% end %>
-  <% end %>
-<% end %>