flowengine 0.1.0 → 0.1.2

data/Rakefile

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'timeout'
-require 'yard'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "timeout"
+require "yard"
 
 def shell(*args)
-  puts "running: #{args.join(' ')}"
-  system(args.join(' '))
+  puts "running: #{args.join(" ")}"
+  system(args.join(" "))
 end
 
 task :clean do
-  shell('rm -rf pkg/ tmp/ coverage/ doc/ ' )
+  shell("rm -rf pkg/ tmp/ coverage/ doc/ ")
 end
 
 task gem: [:build] do
-  shell('gem install pkg/*')
+  shell("gem install pkg/*")
 end
 
 task permissions: [:clean] do
@@ -26,9 +26,9 @@ end
 task build: :permissions
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w(lib/**/*.rb exe/*.rb - README.md LICENSE.txt)
-  t.options.unshift('--title', '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
-  t.after = -> { exec('open doc/index.html') } if RUBY_PLATFORM =~ /darwin/
+  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt CHANGELOG.md]
+  t.options.unshift("--title", '"FlowEngine — DSL + AST for buildiong complex flows in Ruby."')
+  t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
 end
 
 RSpec::Core::RakeTask.new(:spec)

data/justfile

@@ -2,6 +2,10 @@ set shell := ["bash", "-c"]
 
 set dotenv-load
 
+[no-exit-message]
+recipes:
+    @just --choose
+
 test:
     @bundle exec rspec
     @bundle exec rubocop
@@ -32,6 +36,11 @@ format:
 lint: 
     @bundle exec rubocop
 
+# Generates library documentation into ./doc folder and opens the browser
+doc:
+    @bundle exec rake doc
+    @open ./doc/index.html
+
 
 check-all: lint test
 

data/lib/flowengine/definition.rb

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Immutable, versionable flow graph: maps step ids to {Node} objects and defines the entry point.
+  # Built by {DSL::FlowBuilder}; consumed by {Engine} for navigation.
+  #
+  # @attr_reader start_step_id [Symbol] id of the first step in the flow
+  # @attr_reader steps [Hash<Symbol, Node>] frozen map of step id => node (read-only)
   class Definition
     attr_reader :start_step_id, :steps
 
+    # @param start_step_id [Symbol] id of the initial step
+    # @param nodes [Hash<Symbol, Node>] all steps keyed by id
+    # @raise [DefinitionError] if start_step_id is not present in nodes
     def initialize(start_step_id:, nodes:)
       @start_step_id = start_step_id
       @steps = nodes.freeze
@@ -11,14 +19,19 @@ module FlowEngine
       freeze
     end
 
+    # @return [Node] the node for the start step
     def start_step
       step(start_step_id)
     end
 
+    # @param id [Symbol] step id
+    # @return [Node] the node for that step
+    # @raise [UnknownStepError] if id is not in steps
     def step(id)
       steps.fetch(id) { raise UnknownStepError, "Unknown step: #{id.inspect}" }
     end
 
+    # @return [Array<Symbol>] all step ids in the definition
     def step_ids
       steps.keys
     end

data/lib/flowengine/dsl/flow_builder.rb

@@ -2,6 +2,8 @@
 
 module FlowEngine
   module DSL
+    # Builds a {Definition} from the declarative DSL used in {FlowEngine.define}.
+    # Provides {#start} and {#step}; each step block is evaluated by {StepBuilder} with {RuleHelpers}.
     class FlowBuilder
       include RuleHelpers
 
@@ -10,16 +12,27 @@ module FlowEngine
         @nodes = {}
       end
 
+      # Sets the entry step id for the flow.
+      #
+      # @param step_id [Symbol] id of the first step
       def start(step_id)
         @start_step_id = step_id
       end
 
+      # Defines one step by id; the block is evaluated in a {StepBuilder} context.
+      #
+      # @param id [Symbol] step id
+      # @yield block evaluated in {StepBuilder} (type, question, options, transition, etc.)
       def step(id, &)
         builder = StepBuilder.new
         builder.instance_eval(&)
         @nodes[id] = builder.build(id)
       end
 
+      # Produces the frozen {Definition} from the accumulated start and steps.
+      #
+      # @return [Definition]
+      # @raise [DefinitionError] if start was not set or no steps were defined
       def build
         raise DefinitionError, "No start step defined" if @start_step_id.nil?
         raise DefinitionError, "No steps defined" if @nodes.empty?

data/lib/flowengine/dsl/rule_helpers.rb

@@ -2,31 +2,53 @@
 
 module FlowEngine
   module DSL
+    # Factory methods for rule objects, included in {FlowBuilder} and {StepBuilder}.
+    # Use these inside step blocks for transition conditions and visible_if.
     module RuleHelpers
+      # @param field [Symbol] answer key (step id)
+      # @param value [Object] value to check for in the array
+      # @return [Rules::Contains]
       def contains(field, value)
         Rules::Contains.new(field, value)
       end
 
+      # @param field [Symbol] answer key
+      # @param value [Object] expected value
+      # @return [Rules::Equals]
       def equals(field, value)
         Rules::Equals.new(field, value)
       end
 
+      # @param field [Symbol] answer key (value coerced to integer for comparison)
+      # @param value [Integer] threshold
+      # @return [Rules::GreaterThan]
       def greater_than(field, value)
         Rules::GreaterThan.new(field, value)
       end
 
+      # @param field [Symbol] answer key (value coerced to integer for comparison)
+      # @param value [Integer] threshold
+      # @return [Rules::LessThan]
       def less_than(field, value)
         Rules::LessThan.new(field, value)
       end
 
+      # @param field [Symbol] answer key
+      # @return [Rules::NotEmpty]
       def not_empty(field)
         Rules::NotEmpty.new(field)
       end
 
+      # Logical AND of multiple rules.
+      # @param rules [Array<Rules::Base>] rules to combine
+      # @return [Rules::All]
       def all(*rules)
         Rules::All.new(*rules)
       end
 
+      # Logical OR of multiple rules.
+      # @param rules [Array<Rules::Base>] rules to combine
+      # @return [Rules::Any]
       def any(*rules)
         Rules::Any.new(*rules)
       end

data/lib/flowengine/dsl/step_builder.rb

@@ -2,6 +2,8 @@
 
 module FlowEngine
   module DSL
+    # Builds a single {Node} from step DSL (type, question, options, transitions, visibility).
+    # Used by {FlowBuilder#step}; includes {RuleHelpers} for transition/visibility conditions.
     class StepBuilder
       include RuleHelpers
 
@@ -12,32 +14,58 @@ module FlowEngine
         @fields = nil
         @transitions = []
         @visibility_rule = nil
+        @decorations = nil
       end
 
+      # Sets the step/input type (e.g. :multi_select, :number_matrix).
+      # @param value [Symbol]
       def type(value)
         @type = value
       end
 
+      # Sets the prompt/label for the step.
+      # @param text [String]
       def question(text)
         @question = text
       end
 
+      # Sets the list of options for multi-select or choice steps.
+      # @param list [Array]
       def options(list)
         @options = list
       end
 
+      # Sets the list of field names for matrix-style steps (e.g. number_matrix).
+      # @param list [Array]
       def fields(list)
         @fields = list
       end
 
+      # Optional UI decorations (opaque to the engine).
+      # @param decorations [Object]
+      def decorations(decorations)
+        @decorations = decorations
+      end
+
+      # Adds a conditional transition to another step. First matching transition wins.
+      #
+      # @param to [Symbol] target step id
+      # @param if_rule [Rules::Base, nil] condition (nil = unconditional)
       def transition(to:, if_rule: nil)
         @transitions << Transition.new(target: to, rule: if_rule)
       end
 
+      # Sets the visibility rule for this step (DAG mode: step shown only when rule is true).
+      #
+      # @param rule [Rules::Base]
       def visible_if(rule)
         @visibility_rule = rule
       end
 
+      # Builds the {Node} for the given step id from accumulated attributes.
+      #
+      # @param id [Symbol] step id
+      # @return [Node]
       def build(id)
         Node.new(
           id: id,
@@ -46,7 +74,8 @@ module FlowEngine
           options: @options,
           fields: @fields,
           transitions: @transitions,
-          visibility_rule: @visibility_rule
+          visibility_rule: @visibility_rule,
+          decorations: @decorations
         )
       end
     end

data/lib/flowengine/dsl.rb

@@ -5,6 +5,8 @@ require_relative "dsl/step_builder"
 require_relative "dsl/flow_builder"
 
 module FlowEngine
+  # Namespace for the declarative flow DSL: {FlowBuilder} builds a {Definition} from blocks,
+  # {StepBuilder} builds individual {Node}s, and {RuleHelpers} provide rule factory methods.
   module DSL
   end
 end

data/lib/flowengine/engine.rb

@@ -1,9 +1,18 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Runtime session that drives flow navigation: holds definition, answers, and current step.
+  # Validates each answer via an optional {Validation::Adapter}, then advances using node transitions.
+  #
+  # @attr_reader definition [Definition] immutable flow definition
+  # @attr_reader answers [Hash] step_id => value (mutable as user answers)
+  # @attr_reader history [Array<Symbol>] ordered list of step ids visited (including current)
+  # @attr_reader current_step_id [Symbol, nil] current step id, or nil when flow is finished
   class Engine
     attr_reader :definition, :answers, :history, :current_step_id
 
+    # @param definition [Definition] the flow to run
+    # @param validator [Validation::Adapter] validator for step answers (default: {Validation::NullAdapter})
     def initialize(definition, validator: Validation::NullAdapter.new)
       @definition = definition
       @answers = {}
@@ -13,16 +22,23 @@ module FlowEngine
       @history << @current_step_id
     end
 
+    # @return [Node, nil] current step node, or nil if flow is finished
     def current_step
       return nil if finished?
 
       definition.step(@current_step_id)
     end
 
+    # @return [Boolean] true when there is no current step (flow ended)
     def finished?
       @current_step_id.nil?
     end
 
+    # Submits an answer for the current step, validates it, stores it, and advances to the next step.
+    #
+    # @param value [Object] user's answer for the current step
+    # @raise [AlreadyFinishedError] if the flow has already finished
+    # @raise [ValidationError] if the validator rejects the value
     def answer(value)
       raise AlreadyFinishedError, "Flow is already finished" if finished?
 
@@ -33,8 +49,74 @@ module FlowEngine
       advance_step
     end
 
+    # Serializable state for persistence or resumption.
+    #
+    # @return [Hash] current_step_id, answers, and history (string/symbol keys as stored)
+    def to_state
+      {
+        current_step_id: @current_step_id,
+        answers: @answers,
+        history: @history
+      }
+    end
+
+    # Rebuilds an engine from a previously saved state (e.g. from DB or session).
+    #
+    # @param definition [Definition] same definition used when state was captured
+    # @param state_hash [Hash] hash with :current_step_id, :answers, :history (keys may be strings)
+    # @param validator [Validation::Adapter] validator to use (default: NullAdapter)
+    # @return [Engine] restored engine instance
+    def self.from_state(definition, state_hash, validator: Validation::NullAdapter.new)
+      state = symbolize_state(state_hash)
+      engine = allocate
+      engine.send(:restore_state, definition, state, validator)
+      engine
+    end
+
+    # Normalizes a state hash so step ids and history entries are symbols; answers keys are symbols.
+    #
+    # @param hash [Hash] raw state (e.g. from JSON)
+    # @return [Hash] symbolized state
+    def self.symbolize_state(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), result|
+        sym_key = key.to_sym
+        result[sym_key] = case sym_key
+                          when :current_step_id
+                            value&.to_sym
+                          when :history
+                            Array(value).map { |v| v&.to_sym }
+                          when :answers
+                            symbolize_answers(value)
+                          else
+                            value
+                          end
+      end
+    end
+
+    # @param answers [Hash] answers map (keys may be strings)
+    # @return [Hash] same map with symbol keys
+    def self.symbolize_answers(answers)
+      return {} unless answers.is_a?(Hash)
+
+      answers.each_with_object({}) do |(key, value), result|
+        result[key.to_sym] = value
+      end
+    end
+
+    private_class_method :symbolize_state, :symbolize_answers
+
     private
 
+    def restore_state(definition, state, validator)
+      @definition = definition
+      @validator = validator
+      @current_step_id = state[:current_step_id]
+      @answers = state[:answers] || {}
+      @history = state[:history] || []
+    end
+
     def advance_step
       node = definition.step(@current_step_id)
       next_id = node.next_step_id(answers)

data/lib/flowengine/errors.rb

@@ -1,10 +1,21 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Base exception for all flowengine errors.
   class Error < StandardError; end
+
+  # Raised when a flow definition is invalid (e.g. missing start step, unknown step reference).
   class DefinitionError < Error; end
+
+  # Raised when navigating to or requesting a step id that does not exist in the definition.
   class UnknownStepError < Error; end
+
+  # Base exception for runtime engine errors (e.g. validation, already finished).
   class EngineError < Error; end
+
+  # Raised when {Engine#answer} is called after the flow has already finished.
   class AlreadyFinishedError < EngineError; end
+
+  # Raised when the validator rejects the user's answer for the current step.
   class ValidationError < EngineError; end
 end

data/lib/flowengine/evaluator.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # Evaluates rule AST nodes against a given answer context.
+  # Used by transitions and visibility checks; rule objects implement {Rules::Base#evaluate}.
+  #
+  # @attr_reader answers [Hash] current answer state (step_id => value)
   class Evaluator
     attr_reader :answers
 
+    # @param answers [Hash] answer context to evaluate rules against
     def initialize(answers)
       @answers = answers
     end
 
+    # Evaluates a single rule (or returns true if rule is nil).
+    #
+    # @param rule [Rules::Base, nil] rule to evaluate
+    # @return [Boolean] result of rule#evaluate(answers), or true when rule is nil
     def evaluate(rule)
       return true if rule.nil?
 

data/lib/flowengine/graph/mermaid_exporter.rb

@@ -2,15 +2,22 @@
 
 module FlowEngine
   module Graph
+    # Exports a flow {Definition} to Mermaid flowchart syntax for visualization.
+    # Nodes are labeled with truncated question text; edges show condition labels when present.
     class MermaidExporter
+      # Maximum characters for node labels in the diagram (longer text is truncated with "...").
       MAX_LABEL_LENGTH = 50
 
       attr_reader :definition
 
+      # @param definition [Definition] flow to export
       def initialize(definition)
         @definition = definition
       end
 
+      # Generates Mermaid flowchart TD (top-down) source.
+      #
+      # @return [String] Mermaid diagram source (e.g. for Mermaid.js or docs)
       def export
         lines = ["flowchart TD"]
 

data/lib/flowengine/node.rb

@@ -1,13 +1,39 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # A single step in the flow: question metadata, input config, and conditional transitions.
+  # Used by {Engine} to determine the next step and by UI/export to render the step.
+  #
+  # @attr_reader id [Symbol] unique step identifier
+  # @attr_reader type [Symbol] input type (e.g. :multi_select, :number_matrix)
+  # @attr_reader question [String] prompt text for the step
+  # @attr_reader options [Array, nil] choices for multi_select; nil for other types
+  # @attr_reader fields [Array, nil] field names for number_matrix etc.; nil otherwise
+  # @attr_reader transitions [Array<Transition>] ordered list of conditional next-step rules
+  # @attr_reader visibility_rule [Rules::Base, nil] rule controlling whether this node is visible (DAG mode)
   class Node
     attr_reader :id, :type, :question, :options, :fields, :transitions, :visibility_rule
 
-    def initialize(id:, type:, question:, options: nil, fields: nil, transitions: [], visibility_rule: nil)
+    # @param id [Symbol] step id
+    # @param type [Symbol] step/input type
+    # @param question [String] label/prompt
+    # @param decorations [Object, nil] optional UI decorations (not used by engine)
+    # @param options [Array, nil] option list for multi_select
+    # @param fields [Array, nil] field list for matrix-style steps
+    # @param transitions [Array<Transition>] conditional next-step transitions (default: [])
+    # @param visibility_rule [Rules::Base, nil] optional rule for visibility (default: always visible)
+    def initialize(id:, # rubocop:disable Metrics/ParameterLists
+                   type:,
+                   question:,
+                   decorations: nil,
+                   options: nil,
+                   fields: nil,
+                   transitions: [],
+                   visibility_rule: nil)
       @id = id
       @type = type
       @question = question
+      @decorations = decorations
       @options = options&.freeze
       @fields = fields&.freeze
       @transitions = transitions.freeze
@@ -15,11 +41,19 @@ module FlowEngine
       freeze
     end
 
+    # Resolves the next step id from current answers by evaluating transitions in order.
+    #
+    # @param answers [Hash] current answer state (step_id => value)
+    # @return [Symbol, nil] id of the next step, or nil if no transition matches (flow end)
     def next_step_id(answers)
       match = transitions.find { |t| t.applies?(answers) }
       match&.target
     end
 
+    # Whether this node should be considered visible given current answers (for DAG/visibility).
+    #
+    # @param answers [Hash] current answer state
+    # @return [Boolean] true if no visibility_rule, else result of rule evaluation
     def visible?(answers)
       return true if visibility_rule.nil?
 

data/lib/flowengine/rules/all.rb

@@ -2,19 +2,26 @@
 
 module FlowEngine
   module Rules
+    # Composite rule: logical AND of multiple sub-rules. All must be true.
+    #
+    # @attr_reader rules [Array<Base>] sub-rules to evaluate
     class All < Base
       attr_reader :rules
 
+      # @param rules [Array<Base>] one or more rules (arrays are flattened)
       def initialize(*rules)
         super()
         @rules = rules.flatten.freeze
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if every sub-rule evaluates to true
       def evaluate(answers)
         rules.all? { |rule| rule.evaluate(answers) }
       end
 
+      # @return [String] e.g. "(rule1 AND rule2 AND rule3)"
       def to_s
         "(#{rules.join(" AND ")})"
       end

data/lib/flowengine/rules/any.rb

@@ -2,19 +2,26 @@
 
 module FlowEngine
   module Rules
+    # Composite rule: logical OR of multiple sub-rules. At least one must be true.
+    #
+    # @attr_reader rules [Array<Base>] sub-rules to evaluate
     class Any < Base
       attr_reader :rules
 
+      # @param rules [Array<Base>] one or more rules (arrays are flattened)
       def initialize(*rules)
         super()
         @rules = rules.flatten.freeze
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if any sub-rule evaluates to true
       def evaluate(answers)
         rules.any? { |rule| rule.evaluate(answers) }
       end
 
+      # @return [String] e.g. "(rule1 OR rule2 OR rule3)"
       def to_s
         "(#{rules.join(" OR ")})"
       end

data/lib/flowengine/rules/base.rb

@@ -2,11 +2,20 @@
 
 module FlowEngine
   module Rules
+    # Abstract base for rule AST nodes. Subclasses implement {#evaluate} and {#to_s}
+    # for use in transitions and visibility conditions.
     class Base
+      # Evaluates the rule against the current answer context.
+      #
+      # @param _answers [Hash] step_id => value
+      # @return [Boolean]
       def evaluate(_answers)
         raise NotImplementedError, "#{self.class}#evaluate must be implemented"
       end
 
+      # Human-readable representation (e.g. for graph labels).
+      #
+      # @return [String]
       def to_s
         raise NotImplementedError, "#{self.class}#to_s must be implemented"
       end

data/lib/flowengine/rules/contains.rb

@@ -2,9 +2,16 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field (as an array) includes the given value.
+    # Used for multi-select steps (e.g. "BusinessOwnership in earnings").
+    #
+    # @attr_reader field [Symbol] answer key (step id)
+    # @attr_reader value [Object] value that must be present in the array
     class Contains < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Object] value to check for
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +19,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if answers[field] (as array) includes value
       def evaluate(answers)
         Array(answers[field]).include?(value)
       end
 
+      # @return [String] e.g. "BusinessOwnership in earnings"
       def to_s
         "#{value} in #{field}"
       end

data/lib/flowengine/rules/equals.rb

@@ -2,9 +2,15 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field equals the given value.
+    #
+    # @attr_reader field [Symbol] answer key
+    # @attr_reader value [Object] expected value
     class Equals < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Object] expected value
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +18,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] true if answers[field] == value
       def evaluate(answers)
         answers[field] == value
       end
 
+      # @return [String] e.g. "marital_status == Married"
       def to_s
         "#{field} == #{value}"
       end