easy_flow 0.1.0

data/app/models/easy_flow/step_type.rb

@@ -0,0 +1,67 @@
+module EasyFlow
+  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

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

@@ -0,0 +1,52 @@
+module EasyFlow
+  module Steps
+    class Question
+      include 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/easy_flow/switch.rb

@@ -0,0 +1,15 @@
+module EasyFlow
+  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

data/app/models/easy_flow/terminal.rb

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

data/app/models/easy_flow/validator.rb

@@ -0,0 +1,169 @@
+module EasyFlow
+  class Validator
+    OPTIONAL = { unrouted_value: :unrouted_values, unfollowed_path: :unfollowed_paths, dead_end: :dead_ends }.freeze
+
+    def initialize(document, registry: EasyFlow.registry, checks: EasyFlow.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

data/app/models/easy_flow/version.rb

@@ -0,0 +1,24 @@
+module EasyFlow
+  class Version < ApplicationRecord
+    self.table_name = "easy_flow_versions"
+
+    enum :status, { draft: "draft", live: "live", superseded: "superseded",
+                    retired: "retired", withdrawn: "withdrawn" }
+
+    belongs_to :flow, class_name: "EasyFlow::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

data/app/models/easy_flow/violation.rb

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

data/config/routes.rb

@@ -0,0 +1,2 @@
+EasyFlow::Engine.routes.draw do
+end

data/db/migrate/20260924120000_create_easy_flow_definitions.rb

@@ -0,0 +1,20 @@
+class CreateEasyFlowDefinitions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :easy_flow_definitions do |t|
+      t.string :slug
+      t.string :title
+      t.string :start_label
+      t.string :kind
+      t.string :status, null: false, default: "active"
+      t.string :persists, null: false, default: "unsaved"
+      t.json :document
+      t.integer :definition_cursor
+      t.json :changes_since_version
+      t.json :undo_history
+      t.json :undone_changes
+      t.timestamps
+    end
+
+    add_index :easy_flow_definitions, :slug, unique: true
+  end
+end

data/db/migrate/20260924120100_create_easy_flow_versions.rb

@@ -0,0 +1,16 @@
+class CreateEasyFlowVersions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :easy_flow_versions do |t|
+      t.references :flow, null: false, foreign_key: { to_table: :easy_flow_definitions }
+      t.integer :number, null: false
+      t.json :definition
+      t.json :changes_captured
+      t.string :status, null: false, default: "draft"
+      t.datetime :created_at, null: false
+    end
+
+    add_index :easy_flow_versions, [ :flow_id, :number ], unique: true
+    add_index :easy_flow_versions, :flow_id, unique: true, where: "status = 'live'",
+      name: "index_easy_flow_versions_on_one_live_per_flow"
+  end
+end

data/db/migrate/20260924120200_create_easy_flow_runs.rb

@@ -0,0 +1,13 @@
+class CreateEasyFlowRuns < ActiveRecord::Migration[8.1]
+  def change
+    create_table :easy_flow_runs do |t|
+      t.references :flow, null: false, foreign_key: { to_table: :easy_flow_definitions }
+      t.references :definition_version, null: false, foreign_key: { to_table: :easy_flow_versions }
+      t.references :owner, polymorphic: true
+      t.json :recorded
+      t.string :label
+      t.string :status
+      t.timestamps
+    end
+  end
+end

data/lib/easy_flow/engine.rb

@@ -0,0 +1,20 @@
+module EasyFlow
+  class Engine < ::Rails::Engine
+    isolate_namespace EasyFlow
+
+    initializer "easy_flow.step_types" do |app|
+      app.config.to_prepare do
+        EasyFlow::Start.register
+        EasyFlow::Terminal.register
+
+        EasyFlow::Steps::Question.register
+        EasyFlow::Condition.register
+        EasyFlow::Switch.register
+
+        EasyFlow.check(:unrouted_value)
+        EasyFlow.check(:unfollowed_path)
+        EasyFlow.check(:dead_end)
+      end
+    end
+  end
+end

data/lib/easy_flow/version.rb

@@ -0,0 +1,3 @@
+module EasyFlow
+  VERSION = "0.1.0"
+end

data/lib/easy_flow.rb

@@ -0,0 +1,50 @@
+require "json"
+require "easy_flow/version"
+require "easy_flow/engine"
+
+module EasyFlow
+  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
+  class NotPublished < StandardError; end
+  class NotPermitted < StandardError; end
+  class OutOfService < StandardError; end
+  class Withdrawn < StandardError; end
+
+  DRAWING = "easy_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

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: easy_flow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+description: EasyFlow stores flows as versioned documents of steps and the connections
+  between them, and runs a visitor through the live version one step at a time. Apps
+  register their own step types.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/models/easy_flow/admission.rb
+- app/models/easy_flow/application_record.rb
+- app/models/easy_flow/asked.rb
+- app/models/easy_flow/canvas.rb
+- app/models/easy_flow/change.rb
+- app/models/easy_flow/choice.rb
+- app/models/easy_flow/condition.rb
+- app/models/easy_flow/definition.rb
+- app/models/easy_flow/digest.rb
+- app/models/easy_flow/document.rb
+- app/models/easy_flow/drawing.rb
+- app/models/easy_flow/edge.rb
+- app/models/easy_flow/edit_history.rb
+- app/models/easy_flow/layout.rb
+- app/models/easy_flow/name.rb
+- app/models/easy_flow/node.rb
+- app/models/easy_flow/output.rb
+- app/models/easy_flow/progress.rb
+- app/models/easy_flow/progress/kept.rb
+- app/models/easy_flow/progress/loose.rb
+- app/models/easy_flow/question_runner.rb
+- app/models/easy_flow/registry.rb
+- app/models/easy_flow/run.rb
+- app/models/easy_flow/runner.rb
+- app/models/easy_flow/settings.rb
+- app/models/easy_flow/start.rb
+- app/models/easy_flow/step.rb
+- app/models/easy_flow/step_type.rb
+- app/models/easy_flow/step_type/declaration.rb
+- app/models/easy_flow/steps/question.rb
+- app/models/easy_flow/switch.rb
+- app/models/easy_flow/terminal.rb
+- app/models/easy_flow/validator.rb
+- app/models/easy_flow/version.rb
+- app/models/easy_flow/violation.rb
+- config/routes.rb
+- db/migrate/20260924120000_create_easy_flow_definitions.rb
+- db/migrate/20260924120100_create_easy_flow_versions.rb
+- db/migrate/20260924120200_create_easy_flow_runs.rb
+- lib/easy_flow.rb
+- lib/easy_flow/engine.rb
+- lib/easy_flow/version.rb
+homepage: https://github.com/DYB-Development/easy_flow
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DYB-Development/easy_flow
+  source_code_uri: https://github.com/DYB-Development/easy_flow
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Guided, versioned, branching flows for Rails apps.
+test_files: []