inquirex 0.2.0

data/lefthook.yml

@@ -0,0 +1,35 @@
+output:
+  - summary
+  - failure
+
+pre-commit:
+  parallel: true
+  jobs:
+    - name: lint
+      run: bundle exec rubocop -c .rubocop.yml {staged_files}
+      glob: "*.{rb,Gemfile}"
+      stage_fixed: true
+
+    - name: check for conflict markers and whitespace issues
+      run: git --no-pager diff --check
+
+    # If tests take >1 second, move this (or just the long-running tests) to pre-push.
+    - name: run tests
+      run: just test
+
+    - name: fix rubocop formatting issues
+      run: bundle exec rubocop -a {staged_files}
+      glob: "*.{rb,Gemfile,gemspec}"
+      stage_fixed: true
+
+    - name: spell check
+      run: codespell {staged_files}
+      glob: "*.{rb,md,gemspec}"
+
+    - name: format markdown
+      run: mdformat {staged_files}
+      glob: "*.md"
+      stage_fixed: true
+
+    - name: scan for secrets
+      run: detect-secrets-hook --baseline .secrets.baseline

data/lib/inquirex/answers.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Inquirex
+  # Structured wrapper around the answers collected during flow execution.
+  # Provides dot-notation access, bracket access, dig with dot-separated keys,
+  # and serialization helpers.
+  #
+  # @example
+  #   answers = Inquirex::Answers.new({ filing_status: "single", business: { count: 3 } })
+  #   answers.filing_status          # => "single"
+  #   answers[:filing_status]        # => "single"
+  #   answers.business.count         # => 3 (nested dot-notation)
+  #   answers.dig("business.count")  # => 3
+  #   answers.to_flat_h              # => { "filing_status" => "single", "business.count" => 3 }
+  class Answers
+    # @param data [Hash] flat or nested hash of answers (symbol or string keys)
+    def initialize(data = {})
+      @data = deep_symbolize(data).freeze
+    end
+
+    # Bracket access (symbol or string key).
+    #
+    # @param key [Symbol, String]
+    # @return [Object, Answers, nil]
+    def [](key)
+      wrap(@data[key.to_sym])
+    end
+
+    # Dot-notation access.
+    #
+    # @raise [NoMethodError] if the key does not exist (like a real method would)
+    def method_missing(name, *args)
+      return super if args.any? || !@data.key?(name)
+
+      wrap(@data[name])
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @data.key?(name) || super
+    end
+
+    # Dig using dot-separated key string or sequential keys.
+    #
+    # @param keys [Array<String, Symbol>] path components or a single dot-separated string
+    # @return [Object, nil]
+    def dig(*keys)
+      parts = keys.length == 1 ? keys.first.to_s.split(".").map(&:to_sym) : keys.map(&:to_sym)
+      parts.reduce(@data) do |current, key|
+        return nil unless current.is_a?(Hash)
+
+        current[key]
+      end
+    end
+
+    # @return [Hash] nested hash with symbol keys
+    def to_h
+      @data.dup
+    end
+
+    # @return [Hash] flat hash with string dot-notation keys
+    def to_flat_h
+      flatten_hash(@data)
+    end
+
+    # @return [String] JSON representation
+    def to_json(*)
+      JSON.generate(stringify_keys(@data))
+    end
+
+    # @return [Boolean]
+    def ==(other)
+      case other
+      when Answers then @data == other.to_h
+      when Hash    then @data == deep_symbolize(other)
+      else false
+      end
+    end
+
+    # @return [Boolean] true when no answers have been collected
+    def empty?
+      @data.empty?
+    end
+
+    # Number of top-level answer keys.
+    def size
+      @data.size
+    end
+
+    # Merge another hash or Answers into this one (returns new Answers instance).
+    #
+    # @param other [Hash, Answers]
+    # @return [Answers]
+    def merge(other)
+      other_data = other.is_a?(Answers) ? other.to_h : deep_symbolize(other)
+      Answers.new(@data.merge(other_data))
+    end
+
+    def inspect
+      "#<Inquirex::Answers #{@data.inspect}>"
+    end
+
+    private
+
+    def wrap(value)
+      value.is_a?(Hash) ? Answers.new(value) : value
+    end
+
+    def deep_symbolize(hash)
+      hash.each_with_object({}) do |(k, v), result|
+        result[k.to_sym] = v.is_a?(Hash) ? deep_symbolize(v) : v
+      end
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(k, v), result|
+        result[k.to_s] = v.is_a?(Hash) ? stringify_keys(v) : v
+      end
+    end
+
+    def flatten_hash(hash, prefix = nil)
+      hash.each_with_object({}) do |(k, v), result|
+        full_key = prefix ? "#{prefix}.#{k}" : k.to_s
+        if v.is_a?(Hash)
+          result.merge!(flatten_hash(v, full_key))
+        else
+          result[full_key] = v
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/definition.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Inquirex
+  # Immutable, versionable flow graph. Maps step ids to Node objects and defines the entry point.
+  # Carries optional metadata (id, version, title, subtitle, brand) for the JS widget.
+  # Supports JSON round-trip serialization; lambdas are stripped on serialization.
+  #
+  # @attr_reader id [String, nil] flow identifier (e.g. "tax-intake-2025")
+  # @attr_reader version [String] semver string (default: "1.0.0")
+  # @attr_reader meta [Hash] title, subtitle, brand info for the frontend
+  # @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
+  class Definition
+    attr_reader :id, :version, :meta, :start_step_id, :steps
+
+    # @param start_step_id [Symbol] id of the initial step
+    # @param nodes [Hash<Symbol, Node>] all steps keyed by id
+    # @param id [String, nil] flow identifier
+    # @param version [String] semver
+    # @param meta [Hash] frontend metadata
+    # @raise [Errors::DefinitionError] if start_step_id is not present in nodes
+    def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {})
+      @id = id
+      @version = version
+      @meta = meta.freeze
+      @start_step_id = start_step_id.to_sym
+      @steps = nodes.freeze
+      validate!
+      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 [Errors::UnknownStepError] if id is not in steps
+    def step(id)
+      @steps.fetch(id.to_sym) { raise Errors::UnknownStepError, "Unknown step: #{id.inspect}" }
+    end
+
+    # @return [Array<Symbol>] all step ids
+    def step_ids
+      @steps.keys
+    end
+
+    # Serializes the definition to a JSON string.
+    # Lambdas (default procs, compute blocks) are silently stripped.
+    #
+    # @return [String] JSON representation
+    def to_json(*)
+      JSON.generate(to_h)
+    end
+
+    # Serializes to a plain Hash.
+    #
+    # @return [Hash]
+    def to_h
+      hash = {}
+      hash["id"] = @id if @id
+      hash["version"] = @version
+      hash["meta"] = @meta unless @meta.empty?
+      hash["start"] = @start_step_id.to_s
+      hash["steps"] = @steps.transform_keys(&:to_s).transform_values(&:to_h)
+      hash
+    end
+
+    # Deserializes a Definition from a JSON string.
+    #
+    # @param json [String] JSON representation
+    # @return [Definition]
+    def self.from_json(json)
+      from_h(JSON.parse(json))
+    rescue JSON::ParserError => e
+      raise Errors::SerializationError, "Invalid JSON: #{e.message}"
+    end
+
+    # Deserializes a Definition from a plain Hash.
+    #
+    # @param hash [Hash] definition attributes (string or symbol keys)
+    # @return [Definition]
+    def self.from_h(hash)
+      id = hash["id"] || hash[:id]
+      version = hash["version"] || hash[:version] || "1.0.0"
+      meta = hash["meta"] || hash[:meta] || {}
+      start = hash["start"] || hash[:start]
+      steps_data = hash["steps"] || hash[:steps] || {}
+
+      nodes = steps_data.each_with_object({}) do |(step_id, step_hash), acc|
+        sym_id = step_id.to_sym
+        acc[sym_id] = Node.from_h(sym_id, step_hash)
+      end
+
+      new(start_step_id: start, nodes:, id:, version:, meta:)
+    end
+
+    private
+
+    def validate!
+      return if @steps.key?(@start_step_id)
+
+      raise Errors::DefinitionError, "Start step #{@start_step_id.inspect} not found in steps"
+    end
+  end
+end

data/lib/inquirex/dsl/flow_builder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module DSL
+    # Builds a Definition from the declarative DSL block used in Inquirex.define.
+    # Provides start, meta, and all verb methods (ask, say, header, btw, warning, confirm).
+    class FlowBuilder
+      include RuleHelpers
+
+      # @param id [String, nil] optional flow identifier
+      # @param version [String] semver
+      def initialize(id: nil, version: "1.0.0")
+        @flow_id = id
+        @flow_version = version
+        @start_step_id = nil
+        @nodes = {}
+        @meta = {}
+      end
+
+      # Sets the entry step id for the flow.
+      #
+      # @param step_id [Symbol]
+      def start(step_id)
+        @start_step_id = step_id
+      end
+
+      # Sets frontend metadata: title, subtitle, and brand information.
+      #
+      # @param title [String, nil]
+      # @param subtitle [String, nil]
+      # @param brand [Hash, nil] e.g. { name: "Acme", color: "#2563eb" }
+      def meta(title: nil, subtitle: nil, brand: nil)
+        @meta[:title] = title if title
+        @meta[:subtitle] = subtitle if subtitle
+        @meta[:brand] = brand if brand
+      end
+
+      # Defines a question step that collects typed input from the user.
+      #
+      # @param id [Symbol] step id
+      # @yield block evaluated in StepBuilder (type, question, options, transition, etc.)
+      def ask(id, &)
+        add_step(id, :ask, &)
+      end
+
+      # Defines an informational message step (no input collected).
+      #
+      # @param id [Symbol] step id
+      def say(id, &)
+        add_step(id, :say, &)
+      end
+
+      # Defines a section heading step (no input collected).
+      #
+      # @param id [Symbol] step id
+      def header(id, &)
+        add_step(id, :header, &)
+      end
+
+      # Defines an admonition or sidebar note step (no input collected).
+      #
+      # @param id [Symbol] step id
+      def btw(id, &)
+        add_step(id, :btw, &)
+      end
+
+      # Defines an important alert step (no input collected).
+      #
+      # @param id [Symbol] step id
+      def warning(id, &)
+        add_step(id, :warning, &)
+      end
+
+      # Defines a yes/no confirmation gate (collects a boolean answer).
+      #
+      # @param id [Symbol] step id
+      def confirm(id, &)
+        add_step(id, :confirm, &)
+      end
+
+      # Produces the frozen Definition.
+      #
+      # @return [Definition]
+      # @raise [Errors::DefinitionError] if start was not set or no steps were defined
+      def build
+        raise Errors::DefinitionError, "No start step defined" if @start_step_id.nil?
+        raise Errors::DefinitionError, "No steps defined" if @nodes.empty?
+
+        Definition.new(
+          start_step_id: @start_step_id,
+          nodes:         @nodes,
+          id:            @flow_id,
+          version:       @flow_version,
+          meta:          @meta
+        )
+      end
+
+      private
+
+      def add_step(id, verb, &block)
+        builder = StepBuilder.new(verb)
+        builder.instance_eval(&block) if block
+        @nodes[id.to_sym] = builder.build(id)
+      end
+    end
+  end
+end

data/lib/inquirex/dsl/rule_helpers.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module DSL
+    # Factory methods for rule objects. Included in FlowBuilder and StepBuilder
+    # so these helpers are available inside flow/step blocks.
+    module RuleHelpers
+      # @param field [Symbol] answer key (step id)
+      # @param value [Object] value to check for in the array answer
+      # @return [Rules::Contains]
+      def contains(field, value)
+        Rules::Contains.new(field, value)
+      end
+
+      # @param field [Symbol] answer key
+      # @param value [Object] expected exact value
+      # @return [Rules::Equals]
+      def equals(field, value)
+        Rules::Equals.new(field, value)
+      end
+
+      # @param field [Symbol] answer key (value coerced to integer)
+      # @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)
+      # @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: all rules must be true.
+      # @param rules [Array<Rules::Base>]
+      # @return [Rules::All]
+      def all(*rules)
+        Rules::All.new(*rules)
+      end
+
+      # Logical OR: at least one rule must be true.
+      # @param rules [Array<Rules::Base>]
+      # @return [Rules::Any]
+      def any(*rules)
+        Rules::Any.new(*rules)
+      end
+    end
+  end
+end

data/lib/inquirex/dsl/step_builder.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module DSL
+    # Builds a single Node from a step DSL block. Used by FlowBuilder for each verb
+    # (ask, say, header, btw, warning, confirm). Includes RuleHelpers for transition
+    # conditions and skip_if expressions.
+    class StepBuilder
+      include RuleHelpers
+
+      def initialize(verb)
+        @verb = verb
+        @type = nil
+        @question = nil
+        @text = nil
+        @options = nil
+        @transitions = []
+        @skip_if = nil
+        @default = nil
+        @compute = nil
+      end
+
+      # Sets the input data type for :ask steps.
+      # @param value [Symbol] one of Node::TYPES
+      def type(value)
+        @type = value
+      end
+
+      # Sets the prompt/question text for collecting steps.
+      # @param text [String]
+      def question(text)
+        @question = text
+      end
+
+      # Sets the display text for non-collecting steps (say/header/btw/warning).
+      # @param content [String]
+      def text(content)
+        @text = content
+      end
+
+      # Sets the list of options for :enum or :multi_enum steps.
+      # Accepts an Array (option keys) or a Hash (key => label).
+      # @param list [Array, Hash]
+      def options(list)
+        @options = list
+      end
+
+      # Adds a conditional transition. First matching transition wins.
+      #
+      # @param to [Symbol] target step id
+      # @param if_rule [Rules::Base, nil] condition (nil = unconditional)
+      # @param requires_server [Boolean] whether this transition needs server round-trip
+      def transition(to:, if_rule: nil, requires_server: false)
+        @transitions << Transition.new(target: to, rule: if_rule, requires_server:)
+      end
+
+      # Sets a rule that skips this step entirely when true.
+      # The step is omitted from the user's path and no answer is recorded.
+      #
+      # @param rule [Rules::Base]
+      def skip_if(rule)
+        @skip_if = rule
+      end
+
+      # Sets a default value for this step (shown pre-filled; user can change it).
+      # Can be a static value or a proc receiving collected answers so far.
+      #
+      # @param value [Object, Proc]
+      def default(value = nil, &block)
+        @default = block || value
+      end
+
+      # Registers a compute block: auto-calculates a value from answers, not shown to user.
+      # The computed value is stored server-side only and stripped from JSON serialization.
+      #
+      # @yield [Answers] block receiving answers, must return the computed value
+      def compute(&block)
+        @compute = block
+      end
+
+      # Builds the Node for the given step id.
+      #
+      # @param id [Symbol]
+      # @return [Node]
+      def build(id)
+        Node.new(
+          id:,
+          verb:        @verb,
+          type:        resolve_type,
+          question:    @question,
+          text:        @text,
+          options:     @options,
+          transitions: @transitions,
+          skip_if:     @skip_if,
+          default:     @default
+        )
+      end
+
+      private
+
+      def resolve_type
+        # :confirm is sugar for :ask with type :boolean
+        return :boolean if @verb == :confirm && @type.nil?
+
+        @type
+      end
+    end
+  end
+end

data/lib/inquirex/dsl.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Namespace for the declarative flow DSL.
+  # FlowBuilder builds a Definition from blocks; StepBuilder builds individual Nodes;
+  # RuleHelpers provides rule factory methods available inside flow and step blocks.
+  module DSL
+  end
+end

data/lib/inquirex/engine/state_serializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Inquirex
+  class Engine
+    # Handles state serialization for Engine persistence (DB, session store, etc.).
+    # Normalizes string-keyed hashes (from JSON round-trips) to symbol-keyed hashes.
+    module StateSerializer
+      SYMBOLIZERS = {
+        current_step_id: ->(v) { v&.to_sym },
+        history:         ->(v) { Array(v).map { |e| e&.to_sym } },
+        answers:         ->(v) { symbolize_answers(v) }
+      }.freeze
+
+      # Normalizes a state hash so step ids and history entries are symbols.
+      #
+      # @param hash [Hash] raw state (may have string keys from JSON)
+      # @return [Hash] normalized state with symbol keys
+      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] = SYMBOLIZERS.fetch(sym_key, ->(v) { v }).call(value)
+        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({}) { |(k, v), h| h[k.to_sym] = v }
+      end
+    end
+  end
+end