flowengine 0.1.0 → 0.1.2

data/lib/flowengine/rules/greater_than.rb

@@ -2,9 +2,15 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field (coerced to integer) is greater than the threshold.
+    #
+    # @attr_reader field [Symbol] answer key
+    # @attr_reader value [Integer] threshold
     class GreaterThan < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Integer] threshold
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +18,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers (field value is coerced with to_i)
+      # @return [Boolean] true if answers[field].to_i > value
       def evaluate(answers)
         answers[field].to_i > value
       end
 
+      # @return [String] e.g. "business_income > 100000"
       def to_s
         "#{field} > #{value}"
       end

data/lib/flowengine/rules/less_than.rb

@@ -2,9 +2,15 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field (coerced to integer) is less than the threshold.
+    #
+    # @attr_reader field [Symbol] answer key
+    # @attr_reader value [Integer] threshold
     class LessThan < Base
       attr_reader :field, :value
 
+      # @param field [Symbol] answer key
+      # @param value [Integer] threshold
       def initialize(field, value)
         super()
         @field = field
@@ -12,10 +18,13 @@ module FlowEngine
         freeze
       end
 
+      # @param answers [Hash] current answers (field value is coerced with to_i)
+      # @return [Boolean] true if answers[field].to_i < value
       def evaluate(answers)
         answers[field].to_i < value
       end
 
+      # @return [String] e.g. "age < 18"
       def to_s
         "#{field} < #{value}"
       end

data/lib/flowengine/rules/not_empty.rb

@@ -2,15 +2,21 @@
 
 module FlowEngine
   module Rules
+    # Rule: the answer for the given field is present and not empty (nil or empty? => false).
+    #
+    # @attr_reader field [Symbol] answer key
     class NotEmpty < Base
       attr_reader :field
 
+      # @param field [Symbol] answer key
       def initialize(field)
         super()
         @field = field
         freeze
       end
 
+      # @param answers [Hash] current answers
+      # @return [Boolean] false if nil or empty, true otherwise
       def evaluate(answers)
         val = answers[field]
         return false if val.nil?
@@ -19,6 +25,7 @@ module FlowEngine
         true
       end
 
+      # @return [String] e.g. "name is not empty"
       def to_s
         "#{field} is not empty"
       end

data/lib/flowengine/transition.rb

@@ -1,19 +1,33 @@
 # frozen_string_literal: true
 
 module FlowEngine
+  # A single edge from one step to another, optionally guarded by a rule.
+  # Transitions are evaluated in order; the first whose rule is true determines the next step.
+  #
+  # @attr_reader target [Symbol] id of the step to go to when this transition applies
+  # @attr_reader rule [Rules::Base, nil] condition; nil means unconditional (always applies)
   class Transition
     attr_reader :target, :rule
 
+    # @param target [Symbol] next step id
+    # @param rule [Rules::Base, nil] optional condition (nil = always)
     def initialize(target:, rule: nil)
       @target = target
       @rule = rule
       freeze
     end
 
+    # Human-readable label for the condition (e.g. for graph export).
+    #
+    # @return [String] rule#to_s or "always" when rule is nil
     def condition_label
       rule ? rule.to_s : "always"
     end
 
+    # Whether this transition should be taken given current answers.
+    #
+    # @param answers [Hash] current answer state
+    # @return [Boolean] true if rule is nil or rule evaluates to true
     def applies?(answers)
       return true if rule.nil?
 

data/lib/flowengine/validation/adapter.rb

@@ -2,21 +2,34 @@
 
 module FlowEngine
   module Validation
+    # Result of validating a step answer: either valid or a list of error messages.
+    #
+    # @attr_reader errors [Array<String>] validation error messages (empty when valid)
     class Result
       attr_reader :errors
 
+      # @param valid [Boolean] whether the input passed validation
+      # @param errors [Array<String>] error messages (default: [])
       def initialize(valid:, errors: [])
         @valid = valid
         @errors = errors.freeze
         freeze
       end
 
+      # @return [Boolean] true if validation passed
       def valid?
         @valid
       end
     end
 
+    # Abstract adapter for step-level validation. Implement {#validate} to plug in
+    # dry-validation, JSON Schema, or other validators; the engine does not depend on a specific one.
     class Adapter
+      # Validates the user's input for the given step.
+      #
+      # @param _node [Node] the current step (for schema/constraints)
+      # @param _input [Object] the value submitted by the user
+      # @return [Result] valid: true/false and optional errors list
       def validate(_node, _input)
         raise NotImplementedError, "#{self.class}#validate must be implemented"
       end

data/lib/flowengine/validation/null_adapter.rb

@@ -2,7 +2,11 @@
 
 module FlowEngine
   module Validation
+    # No-op validator: always accepts any input. Used by default when no validation adapter is given.
     class NullAdapter < Adapter
+      # @param _node [Node] ignored
+      # @param _input [Object] ignored
+      # @return [Result] always valid with no errors
       def validate(_node, _input)
         Result.new(valid: true, errors: [])
       end

data/lib/flowengine/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module FlowEngine
-  VERSION = "0.1.0"
+  # Semantic version of the flowengine gem (major.minor.patch).
+  VERSION = "0.1.2"
 end

data/lib/flowengine.rb

@@ -20,10 +20,53 @@ require_relative "flowengine/engine"
 require_relative "flowengine/dsl"
 require_relative "flowengine/graph/mermaid_exporter"
 
+# Declarative flow definition and execution engine for wizards, intake forms, and
+# multi-step decision graphs. Separates flow logic, data schema, and UI rendering.
+#
+# @example Define and run a flow
+#   definition = FlowEngine.define do
+#     start :earnings
+#     step :earnings do
+#       type :multi_select
+#       question "What are your main earnings?"
+#       options %w[W2 1099 BusinessOwnership]
+#       transition to: :business_details, if: contains(:earnings, "BusinessOwnership")
+#     end
+#     step :business_details do
+#       type :number_matrix
+#       question "How many business types?"
+#       fields %w[RealEstate SCorp CCorp]
+#     end
+#   end
+#   engine = FlowEngine::Engine.new(definition)
+#   engine.answer(["W2", "BusinessOwnership"])
+#   engine.current_step_id # => :business_details
+#
 module FlowEngine
+  # Builds an immutable {Definition} from the declarative DSL block.
+  #
+  # @yield context of {DSL::FlowBuilder} (start, step, and rule helpers)
+  # @return [Definition] frozen flow definition with start step and nodes
+  # @raise [DefinitionError] if no start step or no steps are defined
   def self.define(&)
     builder = DSL::FlowBuilder.new
     builder.instance_eval(&)
     builder.build
   end
+
+  # Evaluates a string of DSL code and returns the resulting definition.
+  # Intended for loading flow definitions from files or stored text.
+  #
+  # @param text [String] Ruby source containing FlowEngine.define { ... }
+  # @return [Definition] the definition produced by evaluating the DSL
+  # @raise [DefinitionError] on syntax or evaluation errors
+  def self.load_dsl(text)
+    # rubocop:disable Security/Eval
+    eval(text, TOPLEVEL_BINDING.dup, "(dsl)", 1)
+    # rubocop:enable Security/Eval
+  rescue SyntaxError => e
+    raise DefinitionError, "DSL syntax error: #{e.message}"
+  rescue StandardError => e
+    raise DefinitionError, "DSL evaluation error: #{e.message}"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flowengine
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -67,6 +67,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/floweingine-architecture.png
 - docs/flowengine-example.png
 - exe/flowengine
 - justfile