flowengine 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50117723ca62a9851b0c8091e2619132d6e2f849e62b765dadd5c0d0d5c601ad
-  data.tar.gz: 0024ae08e3d6068d0ed913067368ddd4764a83f9ffe1f44e4d9bdcef4f544757
+  metadata.gz: 758428572c105952cb5cf538db6ff0307b60c2a5cbf6187344664d2d063d680a
+  data.tar.gz: e4b3db255b71a7faa3f54f024d96440dbf62aaa383d4a01d96ac5bff58517bcb
 SHA512:
-  metadata.gz: 8d3e5eb92cf044bed6e4a5408ed70452dc755234030e3a39785714864c09d2ba804592cca29005f304dab0fab95058f142602f0239e2f68ffa9826ef15bd748d
-  data.tar.gz: f889c3914f22d5a6cb4f439e202c318819e007a692f973bef4a288c4c4bbb34995aa65bf88bd5ddc799ee3ed684ae41066617300d7b3e67efe4e62437717149d
+  metadata.gz: 6ebe4ebeaf8f47846fe4e831457de894a43e0e544c0f99453ecb9f6d1d535edcef2f8e5f83fc866984e731c865d1e0b6b8ecc3aa46e64b220fb44942441f3491
+  data.tar.gz: 6447ed169da61924456f6f7007b6373ad8f42cc03a667aa3fff7a39198a42b458811e477401c2df385a588466cb85b783ffc8cbf6e187d6a8b2cd8b81cc28112

data/README.md

@@ -8,10 +8,12 @@ This gem does not have any UI or an interactive component. It is used as the fou
 
 The simplest way to see this in action is to use the companion gem [`flowengine-cli`](https://rubygems.org/gems/flowengine-cli), which, given the flow DSL will walk the user through the questioniare according to the DSL flow definition, but using terminal UI and ASCII-based flow.
 
-A declarative flow engine for building rules-driven wizards and intake forms in pure Ruby.
+**A slightly different explanation is that it offere a declarative flow engine for building rules-driven wizards and intake forms in pure Ruby.**
 
-FlowEngine lets you define multi-step flows as **directed graphs** with **conditional branching**, evaluate transitions using an **AST-based rule system**, and collect structured answers through a **stateful runtime engine** — all without framework dependencies.
+> [!NOTE]
+> FlowEngine lets you define multi-step flows as **directed graphs** with **conditional branching**, evaluate transitions using an **AST-based rule system**, and collect structured answers through a **stateful runtime engine** — all without framework dependencies.
 
+> [!CAUTION]
 > **This is not a form builder.** It's a *Form Definition Engine* that separates flow logic, data schema, and UI rendering into independent concerns.
 
 ## Installation

data/Rakefile

@@ -26,7 +26,7 @@ end
 task build: :permissions
 
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w[lib/**/*.rb exe/*.rb - README.md LICENSE.txt]
+  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

data/justfile

@@ -36,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
 
@@ -15,34 +17,55 @@ module FlowEngine
         @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,

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,6 +49,9 @@ 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,
@@ -41,6 +60,12 @@ module FlowEngine
       }
     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
@@ -48,6 +73,10 @@ module FlowEngine
       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)
 
@@ -66,6 +95,8 @@ module FlowEngine
       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)
 

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,9 +1,27 @@
 # 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
 
+    # @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:,
@@ -23,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

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.1"
+  # Semantic version of the flowengine gem (major.minor.patch).
+  VERSION = "0.1.2"
 end

data/lib/flowengine.rb

@@ -20,13 +20,46 @@ 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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flowengine
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Konstantin Gredeskoul