inquirex 0.7.0 → 0.9.4

data/lib/inquirex/template.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module Inquirex
+  # Renders {{field}} placeholders against collected answers.
+  #
+  # Placeholders are dot-notation keys resolved via Answers#to_flat_h
+  # ("{{email}}", "{{business.count}}"). The syntax is deliberately inert —
+  # no code execution — so flow definitions stored in a database can be
+  # rendered server-side safely and a visual editor can preview templates
+  # client-side. It matches the {{field}} placeholder convention used by
+  # inquirex-llm prompts.
+  #
+  # Rendering modes:
+  # - render_text — values inserted verbatim
+  # - render_html — every interpolated value is HTML-escaped
+  #
+  # The built-in {{answers_summary}} placeholder expands to all collected
+  # answers: "key: value" lines in text mode, a simple table in HTML mode.
+  # Unknown fields render as empty strings; array values join with ", ".
+  module Template
+    # Matches one {{field}} placeholder; capture 1 is the dot-notation key.
+    PLACEHOLDER = /\{\{\s*([\w.]+)\s*\}\}/
+    # Reserved placeholder key that expands to a summary of all collected answers.
+    SUMMARY_KEY = "answers_summary"
+
+    module_function
+
+    # @param string [String] template with {{field}} placeholders
+    # @param answers [Answers]
+    # @return [String]
+    def render_text(string, answers)
+      render(string, answers, html: false)
+    end
+
+    # @example Interpolated values are HTML-escaped
+    #   answers = Inquirex::Answers.new(name: "Bob & Sons")
+    #   Inquirex::Template.render_html("<p>{{name}}</p>", answers)
+    #   # => "<p>Bob &amp; Sons</p>"
+    #
+    # @param string [String] template with {{field}} placeholders
+    # @param answers [Answers]
+    # @return [String]
+    def render_html(string, answers)
+      render(string, answers, html: true)
+    end
+
+    # Shared implementation behind render_text and render_html.
+    #
+    # @param string [String] template with {{field}} placeholders
+    # @param answers [Answers]
+    # @param html [Boolean] whether to HTML-escape interpolated values
+    # @return [String]
+    def render(string, answers, html:)
+      flat = answers.to_flat_h
+      string.gsub(PLACEHOLDER) do
+        key = Regexp.last_match(1)
+        next(html ? summary_html(flat) : summary_text(flat)) if key == SUMMARY_KEY
+
+        value = format_value(flat[key])
+        html ? CGI.escapeHTML(value) : value
+      end
+    end
+
+    # Formats a single answer value for interpolation.
+    #
+    # @param value [Object] raw answer value (nil renders as "")
+    # @return [String] arrays joined with ", ", everything else via #to_s
+    def format_value(value)
+      value.is_a?(Array) ? value.join(", ") : value.to_s
+    end
+
+    # Expands {{answers_summary}} in text mode.
+    #
+    # @param flat [Hash{String => Object}] flat answers, dot-notation keys
+    # @return [String] one "key: value" line per answer
+    def summary_text(flat)
+      flat.map { |key, value| "#{key}: #{format_value(value)}" }.join("\n")
+    end
+
+    # Expands {{answers_summary}} in HTML mode.
+    #
+    # @param flat [Hash{String => Object}] flat answers, dot-notation keys
+    # @return [String] a simple HTML table with one row per answer, fully escaped
+    def summary_html(flat)
+      rows = flat.map do |key, value|
+        "<tr><th>#{CGI.escapeHTML(key)}</th><td>#{CGI.escapeHTML(format_value(value))}</td></tr>"
+      end
+      %(<table class="inquirex-answers">#{rows.join}</table>)
+    end
+  end
+end

data/lib/inquirex/transcript.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Formats what the user actually saw into the prose entries a `:text`
+  # accumulator collects.
+  #
+  # The Engine appends one entry per *interaction* — an answered question, a
+  # skipped question, a display step advanced past — and never for a step the
+  # engine elided on its own. A step removed by `skip_if`, or auto-skipped
+  # because an extraction already answered it, was never on screen, so it must
+  # not appear in a narrative that claims to be a record of the session.
+  #
+  # Entries are plain prose rather than JSON because their only consumer is an
+  # LLM prompt: `Q:` / `A:` reads as dialogue to a model, where a serialized
+  # answers hash reads as data and produces a summary that sounds like one.
+  module Transcript
+    # Shown instead of an answer for a question the user declined.
+    SKIPPED = "(skipped)"
+
+    # Shown instead of an answer when a step somehow carries none.
+    NO_ANSWER = "(no answer)"
+
+    class << self
+      # The entry for a display step (say/header/btw/warning) the user has
+      # just advanced past: its text, verbatim.
+      #
+      # @param node [Node] the display step
+      # @return [String, nil] nil when the step carries no text
+      def display_entry(node)
+        text = node.text.to_s.strip
+        text.empty? ? nil : text
+      end
+
+      # The entry for a question the user answered.
+      #
+      # @param node [Node] the collecting step
+      # @param answer [Object] the value the user submitted
+      # @return [String, nil] nil when the step carries no question text
+      def answer_entry(node, answer)
+        exchange(node, format_answer(answer, node))
+      end
+
+      # The entry for an optional question the user declined.
+      #
+      # @param node [Node] the collecting step
+      # @return [String, nil] nil when the step carries no question text
+      def skipped_entry(node)
+        exchange(node, SKIPPED)
+      end
+
+      # Renders an answer the way it was shown, not the way it is stored:
+      # option values become their labels where the step declares them, so the
+      # narrative reads "Married filing jointly" rather than
+      # "married_filing_jointly".
+      #
+      # @param answer [Object] a stored answer value
+      # @param node [Node, nil] the step it belongs to, for label lookup
+      # @return [String]
+      def format_answer(answer, node = nil)
+        case answer
+        when nil        then NO_ANSWER
+        when true       then "Yes"
+        when false      then "No"
+        when Array      then format_array(answer, node)
+        else                 label_for(answer, node)
+        end
+      end
+
+      private
+
+      # @return [String, nil]
+      def exchange(node, rendered)
+        question = node.question.to_s.strip
+        return nil if question.empty?
+
+        "Q: #{question}\nA: #{rendered}"
+      end
+
+      # @return [String]
+      def format_array(answer, node)
+        return NO_ANSWER if answer.empty?
+
+        answer.map { |entry| label_for(entry, node) }.join(", ")
+      end
+
+      # @return [String]
+      def label_for(value, node)
+        labels = node&.option_labels
+        labels&.fetch(value.to_s, nil) || value.to_s
+      end
+    end
+  end
+end

data/lib/inquirex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Inquirex
-  VERSION = "0.7.0"
+  VERSION = "0.9.4"
 end

data/lib/inquirex.rb

@@ -21,6 +21,7 @@ require_relative "inquirex/widget_registry"
 require_relative "inquirex/transition"
 require_relative "inquirex/evaluator"
 require_relative "inquirex/accumulator"
+require_relative "inquirex/transcript"
 require_relative "inquirex/node"
 require_relative "inquirex/definition"
 require_relative "inquirex/answers"
@@ -30,23 +31,20 @@ require_relative "inquirex/completion_metadata"
 require_relative "inquirex/validation/adapter"
 require_relative "inquirex/validation/null_adapter"
 
-# Post-completion actions
-require_relative "inquirex/actions"
-require_relative "inquirex/actions/template"
-require_relative "inquirex/actions/outbox"
-require_relative "inquirex/actions/base"
-require_relative "inquirex/actions/send_email"
-require_relative "inquirex/actions/webhook"
-require_relative "inquirex/actions/custom"
-require_relative "inquirex/actions/action"
-require_relative "inquirex/actions/runner"
+# Completion emails
+require_relative "inquirex/template"
+require_relative "inquirex/send_email"
 
 # DSL
 require_relative "inquirex/dsl"
 require_relative "inquirex/dsl/rule_helpers"
 require_relative "inquirex/dsl/step_builder"
 require_relative "inquirex/dsl/flow_builder"
-require_relative "inquirex/dsl/action_builder"
+require_relative "inquirex/dsl/send_email_builder"
+
+# Source validation — loads after the DSL builders, whose public methods the
+# allowlist reflects on so it cannot drift from the real vocabulary.
+require_relative "inquirex/safe_source"
 
 # Engine
 require_relative "inquirex/engine/state_serializer"
@@ -108,16 +106,47 @@ module Inquirex
   # Evaluates a string of DSL code and returns the resulting definition.
   # Intended for loading flow definitions from files or stored text.
   #
+  # This is an `eval`. Whenever the text comes from anywhere other than your
+  # own repository — a database column a customer edits, an upload, an LLM, a
+  # visual builder — evaluating it unguarded is arbitrary code execution in
+  # the loading process. {SafeSource.validate!} therefore runs **before** the
+  # eval unless you opt out; the ordering is the whole point.
+  #
+  # `unsafe: true` is for source you control as code: a `.rb` file in your own
+  # repository, a fixture, the file a CLI was pointed at. It is named `unsafe`
+  # rather than `safe: false` so the dangerous call is the conspicuous one.
+  #
+  # @example Stored, customer-authored DSL (validated)
+  #   Inquirex.load_dsl(qualifier.flow_dsl)
+  #
+  # @example Your own file (validation skipped)
+  #   Inquirex.load_dsl(File.read("flow.rb"), unsafe: true)
+  #
   # @param text [String] Ruby source containing Inquirex.define { ... }
+  # @param unsafe [Boolean] skip validation — only for source you authored
+  # @param max_bytes [Integer] source size ceiling for validation
+  # @param max_depth [Integer] AST nesting ceiling for validation
   # @return [Definition]
+  # @raise [Errors::UnsafeSourceError] when the source leaves the allowlist
   # @raise [Errors::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 Errors::DefinitionError, "DSL syntax error: #{e.message}"
-  rescue StandardError => e
-    raise Errors::DefinitionError, "DSL evaluation error: #{e.message}"
+  def self.load_dsl(text,
+    unsafe: false,
+    max_bytes: SafeSource.max_source_bytes,
+    max_depth: SafeSource.max_depth)
+    SafeSource.validate!(text, max_bytes:, max_depth:) unless unsafe
+
+    begin
+      # Deliberate eval: the flow DSL *is* Ruby, so there is nothing else to
+      # evaluate it with. Reaching this line means either SafeSource accepted
+      # the source against a default-deny allowlist (above), or the caller
+      # asserted `unsafe: true` for source it authored itself.
+      # rubocop:disable Security/Eval
+      eval(text, TOPLEVEL_BINDING.dup, "(dsl)", 1)
+      # rubocop:enable Security/Eval
+    rescue SyntaxError => e
+      raise Errors::DefinitionError, "DSL syntax error: #{e.message}"
+    rescue StandardError => e
+      raise Errors::DefinitionError, "DSL evaluation error: #{e.message}"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.4
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -42,22 +42,13 @@ files:
 - lib/.DS_Store
 - lib/inquirex.rb
 - lib/inquirex/accumulator.rb
-- lib/inquirex/actions.rb
-- lib/inquirex/actions/action.rb
-- lib/inquirex/actions/base.rb
-- lib/inquirex/actions/custom.rb
-- lib/inquirex/actions/outbox.rb
-- lib/inquirex/actions/runner.rb
-- lib/inquirex/actions/send_email.rb
-- lib/inquirex/actions/template.rb
-- lib/inquirex/actions/webhook.rb
 - lib/inquirex/answers.rb
 - lib/inquirex/completion_metadata.rb
 - lib/inquirex/definition.rb
 - lib/inquirex/dsl.rb
-- lib/inquirex/dsl/action_builder.rb
 - lib/inquirex/dsl/flow_builder.rb
 - lib/inquirex/dsl/rule_helpers.rb
+- lib/inquirex/dsl/send_email_builder.rb
 - lib/inquirex/dsl/step_builder.rb
 - lib/inquirex/engine.rb
 - lib/inquirex/engine/state_serializer.rb
@@ -73,6 +64,13 @@ files:
 - lib/inquirex/rules/greater_than.rb
 - lib/inquirex/rules/less_than.rb
 - lib/inquirex/rules/not_empty.rb
+- lib/inquirex/safe_source.rb
+- lib/inquirex/safe_source/call_spec.rb
+- lib/inquirex/safe_source/validator.rb
+- lib/inquirex/safe_source/vocabulary.rb
+- lib/inquirex/send_email.rb
+- lib/inquirex/template.rb
+- lib/inquirex/transcript.rb
 - lib/inquirex/transition.rb
 - lib/inquirex/validation/adapter.rb
 - lib/inquirex/validation/null_adapter.rb
@@ -102,8 +100,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.17
 specification_version: 4
 summary: A declarative, rules-driven questionnaire engine for building conditionally-branching
-  intake forms, qualification wizards, and surveys in pure Ruby.
+  intake forms, qualification wizards, and surveys in pure Ruby, with additional plugins
+  providing LLM/AI support. See inquirex-llm.
 test_files: []

data/lib/inquirex/actions/action.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module Inquirex
-  module Actions
-    # A named post-completion unit: an optional rule gating execution and an
-    # ordered list of effects. Declared with the DSL word `action`:
-    #
-    #   action :client_receipt, if: not_empty(:email) do
-    #     send_email to: "{{email}}", subject: "Thanks {{name}}!", text: "..."
-    #   end
-    #
-    # Rules reuse the same serializable AST as transitions, so conditions
-    # survive the JSON round-trip. Non-serializable effects (run blocks) are
-    # stripped on serialization; an action left with no serializable effects
-    # is omitted from JSON entirely.
-    class Action
-      attr_reader :id, :rule, :effects
-
-      # @param id [Symbol] action identifier
-      # @param effects [Array<Actions::Base>] executed in declaration order
-      # @param rule [Rules::Base, nil] gate — action runs only when true
-      def initialize(id:, effects:, rule: nil)
-        @id = id.to_sym
-        @effects = effects.freeze
-        @rule = rule
-        freeze
-      end
-
-      # @param answers_hash [Hash] step_id => value context for rule evaluation
-      # @return [Boolean]
-      def applicable?(answers_hash)
-        @rule.nil? || @rule.evaluate(answers_hash)
-      end
-
-      # @return [Boolean] whether anything survives JSON serialization
-      def serializable?
-        @effects.any?(&:serializable?)
-      end
-
-      # @return [Hash] wire format; run blocks are stripped
-      def to_h
-        hash = { "id" => @id.to_s }
-        hash["if"] = @rule.to_h if @rule
-        hash["effects"] = @effects.select(&:serializable?).map(&:to_h)
-        hash
-      end
-
-      # @param hash [Hash] string or symbol keys
-      # @return [Action]
-      def self.from_h(hash)
-        id = hash["id"] || hash[:id]
-        rule_data = hash["if"] || hash[:if]
-        effects_data = hash["effects"] || hash[:effects] || []
-
-        effects = effects_data.map do |effect_hash|
-          type = effect_hash["type"] || effect_hash[:type]
-          Actions.lookup(type).from_h(effect_hash)
-        end
-
-        new(
-          id:      id.to_sym,
-          effects: effects,
-          rule:    rule_data ? Rules::Base.from_h(rule_data) : nil
-        )
-      end
-    end
-  end
-end

data/lib/inquirex/actions/base.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module Inquirex
-  module Actions
-    # Abstract base for action effects — the executable units inside an
-    # `action` block. Subclasses implement #call and, when serializable,
-    # #to_h / .from_h following the same round-trip pattern as Rules::Base.
-    #
-    # Effects that wrap Ruby procs (Actions::Custom) return false from
-    # #serializable? and are stripped from JSON, consistent with how
-    # lambdas are handled everywhere else in Inquirex.
-    class Base
-      # Executes the effect. Email-building effects append Mail::Message
-      # objects to the outbox; custom effects may do anything server-side.
-      #
-      # @param answers [Answers] completed answers
-      # @param outbox [Outbox] collector for built messages
-      # @return [void]
-      def call(answers, outbox)
-        raise NotImplementedError, "#{self.class}#call must be implemented"
-      end
-
-      # @return [Boolean] whether this effect survives JSON serialization
-      def serializable? = true
-
-      # Hook for effects that must be checked against the definition carrying
-      # them (e.g. Webhook vs allowed_domains). Runs inside
-      # Definition#validate!, which both DSL-built and JSON-rehydrated
-      # definitions pass through — so violations fail at load time.
-      #
-      # @param _definition [Definition]
-      # @raise [Errors::DefinitionError] on violation
-      def validate_against(_definition); end
-
-      # @return [Hash]
-      def to_h
-        raise NotImplementedError, "#{self.class}#to_h must be implemented"
-      end
-    end
-  end
-end

data/lib/inquirex/actions/custom.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Inquirex
-  module Actions
-    # Escape-hatch effect wrapping an arbitrary Ruby block, declared in the
-    # DSL as `run { |answers, outbox| ... }`. Full language power — build a
-    # Mail::Message by hand with outbox.add_message, call a service, record
-    # metrics — at the cost of serialization: like every lambda in Inquirex,
-    # the block is stripped from JSON and exists only in Ruby-authored
-    # definitions.
-    class Custom < Base
-      # @param block [Proc] receives (answers, outbox)
-      def initialize(block)
-        super()
-        @block = block
-        freeze
-      end
-
-      # Invokes the wrapped block with the collected answers and the outbox.
-      #
-      # @param answers [Answers] completed answers
-      # @param outbox [Outbox] collector for messages the block may build
-      # @return [Object] whatever the block returns (recorded, not interpreted)
-      def call(answers, outbox)
-        @block.call(answers, outbox)
-      end
-
-      def serializable? = false
-    end
-  end
-end

data/lib/inquirex/actions/outbox.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module Inquirex
-  module Actions
-    # Collected output of running a definition's actions: the Mail::Message
-    # objects built by send_email effects, plus a per-execution result trail.
-    #
-    # The outbox is attached to Answers#outbox and is intentionally excluded
-    # from Answers serialization — mail objects never leak into persisted
-    # answer data. Delivery is the host application's job:
-    #
-    #   answers.outbox.each do |message|
-    #     ActionMailer::Base.wrap_delivery_behavior(message)
-    #     message.deliver
-    #   end
-    class Outbox
-      include Enumerable
-
-      # One entry per effect execution (or per skipped action).
-      # status is :ok, :skipped (action rule was false), or :failed.
-      Result = Data.define(:action_id, :status, :error)
-
-      attr_reader :messages, :results
-
-      def initialize
-        @messages = []
-        @results = []
-      end
-
-      # @param mail [Mail::Message]
-      # @return [Mail::Message]
-      def add_message(mail)
-        @messages << mail
-        mail
-      end
-
-      # @param action_id [Symbol]
-      # @param status [Symbol] :ok, :skipped, or :failed
-      # @param error [StandardError, nil]
-      def record(action_id, status, error: nil)
-        @results << Result.new(action_id:, status:, error:)
-      end
-
-      # Iterates over built Mail::Message objects.
-      def each(&) = @messages.each(&)
-
-      # @return [Integer] number of built messages
-      def size = @messages.size
-
-      # @return [Boolean]
-      def empty? = @messages.empty?
-
-      # @return [Array<Result>] executions that raised
-      def failures = @results.select { |result| result.status == :failed }
-    end
-  end
-end

data/lib/inquirex/actions/runner.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-module Inquirex
-  module Actions
-    # Executes a definition's actions against completed answers, in
-    # declaration order, populating Answers#outbox with built messages and a
-    # result trail.
-    #
-    # Deliberately separate from the Engine: in the cross-site architecture
-    # the frontend collects answers and a different server process
-    # post-processes them, so the runner is a pure function of
-    # (definition, answers) — which also makes rebuilding messages inside a
-    # background job trivial.
-    #
-    # A failing effect records a :failed result and never aborts the other
-    # actions; the host inspects outbox.failures and decides what to do.
-    class Runner
-      # @param definition [Definition]
-      def initialize(definition)
-        @definition = definition
-      end
-
-      # @param answers [Answers, Hash] completed answers (a Hash is wrapped)
-      # @return [Answers] the (possibly wrapped) answers with #outbox populated
-      def call(answers)
-        answers = Answers.new(answers) unless answers.is_a?(Answers)
-        context = answers.to_h
-
-        @definition.actions.each do |action|
-          unless action.applicable?(context)
-            answers.outbox.record(action.id, :skipped)
-            next
-          end
-          execute(action, answers)
-        end
-
-        answers
-      end
-
-      private
-
-      def execute(action, answers)
-        action.effects.each do |effect|
-          effect.call(answers, answers.outbox)
-          answers.outbox.record(action.id, :ok)
-        rescue StandardError => e
-          answers.outbox.record(action.id, :failed, error: e)
-        end
-      end
-    end
-  end
-end