FlowEngine

gem "flowengine"

require "flowengine"

# 1. Define a flow
definition = FlowEngine.define do
  start :name

  step :name do
    type :text
    question "What is your name?"
    transition to: :age
  end

  step :age do
    type :number
    question "How old are you?"
    transition to: :beverage, if_rule: greater_than(:age, 20)
    transition to: :thanks
  end

  step :beverage do
    type :single_select
    question "Pick a drink."
    options %w[Beer Wine Cocktail]
    transition to: :thanks
  end

  step :thanks do
    type :text
    question "Thank you for your responses!"
  end
end

# 2. Run the engine
engine = FlowEngine::Engine.new(definition)

engine.answer("Alice")       # :name    -> :age
engine.answer(25)            # :age     -> :beverage  (25 > 20)
engine.answer("Wine")        # :beverage -> :thanks
engine.answer("ok")          # :thanks  -> finished

engine.finished?  # => true
engine.answers
# => { name: "Alice", age: 25, beverage: "Wine", thanks: "ok" }
engine.history
# => [:name, :age, :beverage, :thanks]

engine.answer("Alice")       # :name    -> :age
engine.answer(18)            # :age     -> :thanks  (18 is NOT > 20)
engine.answer("ok")          # :thanks  -> finished

engine.answers
# => { name: "Alice", age: 18, thanks: "ok" }
engine.history
# => [:name, :age, :thanks]

definition = FlowEngine.define do
  start :first_step     # Required: which node to begin at

  step :first_step do
    # step configuration...
  end

  step :second_step do
    # step configuration...
  end
end

step :filing_status do
  type :single_select                    # One choice from a list
  question "What is your filing status?"
  options %w[single married_filing_jointly married_filing_separately head_of_household]
  transition to: :dependents
end

step :income_types do
  type :multi_select                     # Multiple choices from a list
  question "Select all income types."
  options %w[W2 1099 Business Investment Rental]
  transition to: :business, if_rule: contains(:income_types, "Business")
  transition to: :summary
end

step :dependents do
  type :number                           # A numeric value
  question "How many dependents?"
  transition to: :income_types
end

step :business_details do
  type :number_matrix                    # Multiple named numeric fields
  question "How many of each business type?"
  fields %w[RealEstate SCorp CCorp Trust LLC]
  transition to: :summary
end

step :notes do
  type :text                             # Free-form text
  question "Any additional notes?"
  transition to: :summary
end

step :income_types do
  type :multi_select
  question "Select income types."
  options %w[W2 1099 Business Investment Rental]

  # Conditional transitions (checked in order)
  transition to: :business_count,      if_rule: contains(:income_types, "Business")
  transition to: :investment_details,  if_rule: contains(:income_types, "Investment")
  transition to: :rental_details,      if_rule: contains(:income_types, "Rental")

  # Unconditional fallback (always matches)
  transition to: :state_filing
end

step :spouse_income do
  type :number
  question "What is your spouse's annual income?"
  visible_if equals(:filing_status, "married_filing_jointly")
  transition to: :deductions
end

# AND — all conditions must be true
transition to: :special_review,
           if_rule: all(
             equals(:filing_status, "married_filing_jointly"),
             contains(:income_types, "Business"),
             greater_than(:business_count, 2)
           )

# OR — at least one condition must be true
transition to: :alt_path,
           if_rule: any(
             contains(:income_types, "Investment"),
             contains(:income_types, "Rental")
           )

transition to: :complex_review,
           if_rule: all(
             equals(:filing_status, "married_filing_jointly"),
             any(
               greater_than(:business_count, 3),
               contains(:income_types, "Rental")
             ),
             not_empty(:dependents)
           )

rule = FlowEngine::Rules::Contains.new(:income_types, "Business")
rule.evaluate({ income_types: ["W2", "Business"] })  # => true
rule.evaluate({ income_types: ["W2"] })               # => false

rule = FlowEngine::Rules::All.new(
  FlowEngine::Rules::Equals.new(:status, "married"),
  FlowEngine::Rules::GreaterThan.new(:dependents, 0)
)
rule.evaluate({ status: "married", dependents: 2 })   # => true
rule.evaluate({ status: "single", dependents: 2 })    # => false

definition = FlowEngine.define { ... }
engine = FlowEngine::Engine.new(definition)

# Answering after the flow is complete
engine.answer("extra")
# => raises FlowEngine::AlreadyFinishedError

# Referencing an unknown step in a definition
definition.step(:nonexistent)
# => raises FlowEngine::UnknownStepError

# Invalid definition (start step doesn't exist)
FlowEngine.define do
  start :missing
  step :other do
    type :text
    question "Hello"
  end
end
# => raises FlowEngine::DefinitionError

# The adapter interface
class FlowEngine::Validation::Adapter
  def validate(node, input)
    # Must return a FlowEngine::Validation::Result
    raise NotImplementedError
  end
end

# Result object
FlowEngine::Validation::Result.new(valid: true, errors: [])
FlowEngine::Validation::Result.new(valid: false, errors: ["must be a number"])

class MyValidator < FlowEngine::Validation::Adapter
  def validate(node, input)
    errors = []

    case node.type
    when :number
      errors << "must be a number" unless input.is_a?(Numeric)
    when :single_select
      errors << "invalid option" unless node.options&.include?(input)
    when :multi_select
      unless input.is_a?(Array) && input.all? { |v| node.options&.include?(v) }
        errors << "invalid options"
      end
    end

    FlowEngine::Validation::Result.new(valid: errors.empty?, errors: errors)
  end
end

engine = FlowEngine::Engine.new(definition, validator: MyValidator.new)
engine.answer("not_a_number")  # => raises FlowEngine::ValidationError

exporter = FlowEngine::Graph::MermaidExporter.new(definition)
puts exporter.export

tax_intake = FlowEngine.define do
  start :filing_status

  step :filing_status do
    type :single_select
    question "What is your filing status for 2025?"
    options %w[single married_filing_jointly married_filing_separately head_of_household]
    transition to: :dependents
  end

  step :dependents do
    type :number
    question "How many dependents do you have?"
    transition to: :income_types
  end

  step :income_types do
    type :multi_select
    question "Select all income types that apply to you in 2025."
    options %w[W2 1099 Business Investment Rental Retirement]
    transition to: :business_count,      if_rule: contains(:income_types, "Business")
    transition to: :investment_details,  if_rule: contains(:income_types, "Investment")
    transition to: :rental_details,      if_rule: contains(:income_types, "Rental")
    transition to: :state_filing
  end

  step :business_count do
    type :number
    question "How many total businesses do you own or are a partner in?"
    transition to: :complex_business_info, if_rule: greater_than(:business_count, 2)
    transition to: :business_details
  end

  step :complex_business_info do
    type :text
    question "With more than 2 businesses, please provide your primary EIN and a brief description of each entity."
    transition to: :business_details
  end

  step :business_details do
    type :number_matrix
    question "How many of each business type do you own?"
    fields %w[RealEstate SCorp CCorp Trust LLC]
    transition to: :investment_details, if_rule: contains(:income_types, "Investment")
    transition to: :rental_details,    if_rule: contains(:income_types, "Rental")
    transition to: :state_filing
  end

  step :investment_details do
    type :multi_select
    question "What types of investments do you hold?"
    options %w[Stocks Bonds Crypto RealEstate MutualFunds]
    transition to: :crypto_details,  if_rule: contains(:investment_details, "Crypto")
    transition to: :rental_details,  if_rule: contains(:income_types, "Rental")
    transition to: :state_filing
  end

  step :crypto_details do
    type :text
    question "Please describe your cryptocurrency transactions (exchanges used, approximate number of transactions)."
    transition to: :rental_details, if_rule: contains(:income_types, "Rental")
    transition to: :state_filing
  end

  step :rental_details do
    type :number_matrix
    question "Provide details about your rental properties."
    fields %w[Residential Commercial Vacation]
    transition to: :state_filing
  end

  step :state_filing do
    type :multi_select
    question "Which states do you need to file in?"
    options %w[California NewYork Texas Florida Illinois Other]
    transition to: :foreign_accounts
  end

  step :foreign_accounts do
    type :single_select
    question "Do you have any foreign financial accounts (bank accounts, securities, or financial assets)?"
    options %w[yes no]
    transition to: :foreign_account_details, if_rule: equals(:foreign_accounts, "yes")
    transition to: :deduction_types
  end

  step :foreign_account_details do
    type :number
    question "How many foreign accounts do you have?"
    transition to: :deduction_types
  end

  step :deduction_types do
    type :multi_select
    question "Which additional deductions apply to you?"
    options %w[Medical Charitable Education Mortgage None]
    transition to: :charitable_amount, if_rule: contains(:deduction_types, "Charitable")
    transition to: :contact_info
  end

  step :charitable_amount do
    type :number
    question "What is your total estimated charitable contribution amount for 2025?"
    transition to: :charitable_documentation, if_rule: greater_than(:charitable_amount, 5000)
    transition to: :contact_info
  end

  step :charitable_documentation do
    type :text
    question "For charitable contributions over $5,000, please list the organizations and amounts."
    transition to: :contact_info
  end

  step :contact_info do
    type :text
    question "Please provide your contact information (name, email, phone)."
    transition to: :review
  end

  step :review do
    type :text
    question "Thank you! Please review your information. Type 'confirm' to submit."
  end
end

engine = FlowEngine::Engine.new(tax_intake)

engine.answer("married_filing_jointly")
engine.answer(3)
engine.answer(%w[W2 1099 Business Investment Rental Retirement])
engine.answer(4)
engine.answer("EIN: 12-3456789. Entities: Alpha LLC, Beta SCorp, Gamma LLC, Delta CCorp")
engine.answer({ "RealEstate" => 1, "SCorp" => 1, "CCorp" => 1, "Trust" => 0, "LLC" => 2 })
engine.answer(%w[Stocks Bonds Crypto RealEstate])
engine.answer("Coinbase and Kraken, approximately 150 transactions in 2025")
engine.answer({ "Residential" => 2, "Commercial" => 1, "Vacation" => 0 })
engine.answer(%w[California NewYork])
engine.answer("yes")
engine.answer(3)
engine.answer(%w[Medical Charitable Education Mortgage])
engine.answer(12_000)
engine.answer("Red Cross: $5,000; Habitat for Humanity: $4,000; Local Food Bank: $3,000")
engine.answer("Jane Smith, jane.smith@example.com, 555-123-4567")
engine.answer("confirm")

engine = FlowEngine::Engine.new(tax_intake)

engine.answer("single")
engine.answer(0)
engine.answer(["W2"])
engine.answer(["Texas"])
engine.answer("no")
engine.answer(["None"])
engine.answer("John Doe, john.doe@example.com, 555-987-6543")
engine.answer("confirm")

engine = FlowEngine::Engine.new(tax_intake)

engine.answer("married_filing_separately")
engine.answer(1)
engine.answer(%w[W2 Business Investment])
engine.answer(2)                                    # <= 2 businesses, no complex_business_info
engine.answer({ "RealEstate" => 0, "SCorp" => 1, "CCorp" => 0, "Trust" => 0, "LLC" => 1 })
engine.answer(%w[Stocks Bonds MutualFunds])          # no Crypto, no crypto_details
engine.answer(%w[California Illinois])
engine.answer("no")                                  # no foreign accounts
engine.answer(%w[Charitable Mortgage])
engine.answer(3000)                                  # <= 5000, no documentation needed
engine.answer("Alice Johnson, alice.j@example.com, 555-555-0100")
engine.answer("confirm")

engine = FlowEngine::Engine.new(tax_intake)

engine.answer("head_of_household")
engine.answer(2)
engine.answer(%w[1099 Rental])
engine.answer({ "Residential" => 1, "Commercial" => 0, "Vacation" => 1 })
engine.answer(["Florida"])
engine.answer("yes")
engine.answer(1)
engine.answer(%w[Medical Education])
engine.answer("Bob Lee, bob@example.com, 555-000-1111")
engine.answer("confirm")

definition = FlowEngine.define do
  start :status

  step :status do
    type :single_select
    question "Filing status?"
    options %w[single married]
    transition to: :dependents
  end

  step :dependents do
    type :number
    question "How many dependents?"
    transition to: :income
  end

  step :income do
    type :multi_select
    question "Income types?"
    options %w[W2 Business]

    # All three conditions must be true
    transition to: :special_review,
               if_rule: all(
                 equals(:status, "married"),
                 contains(:income, "Business"),
                 not_empty(:income)
               )

    # At least one condition must be true
    transition to: :alt_review,
               if_rule: any(
                 less_than(:dependents, 2),
                 contains(:income, "W2")
               )

    # Unconditional fallback
    transition to: :default_review
  end

  step :special_review do
    type :text
    question "Married with business income - special review required."
  end

  step :alt_review do
    type :text
    question "Alternative review path."
  end

  step :default_review do
    type :text
    question "Default review."
  end
end