inquirex 0.9.4 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5f521bddfb7ad29c91aa0d99b19615ea43462739ba5da7b0a8ba4ce081fc411
-  data.tar.gz: 9096cdb056678b643213b17193b7228f984babce96f6bd04f22ce631542438f0
+  metadata.gz: 8104ced622e0b1641020699aa84277e7f5ab39e583fb258018c50853ebeaef95
+  data.tar.gz: 2ebcb19ca70047b6dec0db437b0e4e5247619dfa1c9503d956648526825bdfb3
 SHA512:
-  metadata.gz: 982bfd2e952d710be958ce3a2aba4fc0eccdcacfef4a0d761c6afae09e0a7a4fbfadce93e52ce22c736844cd659da58ec4dbdfb654fb7d6b2988783b885d7f5f
-  data.tar.gz: cf62d36c583af4fba6462ca8629187895d14a626ae157df99e5f6a58b0878a1c8b4b97152391dab61767b24449be77d36d0233badd7a17b54c037a3bf85fa1d6
+  metadata.gz: f1960f28308bceb5164274a111725019a1596fa2938800535cf7452355b72a6e644c5a35b1573c2d1aac433e643da604a09af801dc63d114694e0a41ead88216
+  data.tar.gz: e633b465d42e02fb5563f5ad9bbc887d3de07cae1005753e9c1c457f72802cd9015d986b90a5ef6b7af20bd448290366ab3af4471ff26ed0f3115ee0acb5c3ba

data/lib/inquirex/dsl/step_builder.rb

@@ -18,6 +18,7 @@ module Inquirex
         @skip_if = nil
         @default = nil
         @required = true
+        @requiredness = nil
         @compute = nil
         @widget_hints = {}
         @accumulations = []
@@ -138,8 +139,34 @@ module Inquirex
       #   end
       #
       # @param value [Boolean] false to make the step skippable
+      # @raise [Errors::DefinitionError] if the step also declares `optional` to the contrary
       def required(value = true)
-        @required = value
+        assign_requiredness(:required, value ? true : false)
+      end
+
+      # Declares this step skippable — the inverse of {#required}, and the form
+      # most flows want. Since steps are required by default, `required true` is
+      # a no-op and the keyword only ever appears as `required false`; `optional`
+      # says the same thing without the double negative.
+      #
+      # Sugar only: both spellings serialize to the single wire field
+      # `"required": false`, so a definition round-trips identically however it
+      # was authored and no consumer has to learn a second key.
+      #
+      # @example Equivalent to `required false`, and easier to read
+      #   ask :dependents do
+      #     type :integer
+      #     question "How many dependents?"
+      #     optional
+      #     default 0
+      #     transition to: :done
+      #   end
+      #
+      # @param value [Boolean] true (the default) to make the step skippable
+      # @return [void]
+      # @raise [Errors::DefinitionError] if the step also declares `required` to the contrary
+      def optional(value = true)
+        assign_requiredness(:optional, value ? false : true)
       end
 
       # Registers a compute block: auto-calculates a value from answers, not shown to user.
@@ -150,6 +177,51 @@ module Inquirex
         @compute = block
       end
 
+      # Declares the inclusive lower bound of a numeric step.
+      #
+      # Only meaningful for `:integer`, `:decimal` and `:currency`; declaring it
+      # on any other type raises at build time rather than being ignored.
+      #
+      # @example A headcount that cannot be negative
+      #   ask :employees do
+      #     type :integer
+      #     question "How many employees?"
+      #     min 0
+      #     max 500
+      #     transition to: :done
+      #   end
+      #
+      # @param value [Numeric] inclusive lower bound
+      # @return [void]
+      def min(value)
+        @min = value
+      end
+
+      # Declares the inclusive upper bound of a numeric step.
+      #
+      # @param value [Numeric] inclusive upper bound
+      # @return [void]
+      # @see #min
+      def max(value)
+        @max = value
+      end
+
+      # Declares the increment a numeric step's stepper arrows move by.
+      #
+      # Defaults, when unset, to 1 for `:integer` and 0.01 for `:decimal` and
+      # `:currency` — the renderer applies that, not this builder, so an unset
+      # value stays absent from the wire format.
+      #
+      # Spelled `step_size` rather than `step` because a step *is* the unit of
+      # a flow; `steps.employees.step` would read as a nested flow step.
+      #
+      # @param value [Numeric] stepper increment
+      # @return [void]
+      # @see #min
+      def step_size(value)
+        @step_size = value
+      end
+
       # Builds the Node for the given step id.
       #
       # @param id [Symbol]
@@ -166,6 +238,9 @@ module Inquirex
           skip_if:       @skip_if,
           default:       @default,
           required:      @required,
+          min:           @min,
+          max:           @max,
+          step_size:     @step_size,
           widget_hints:  resolve_widget_hints,
           accumulations: @accumulations
         )
@@ -173,6 +248,26 @@ module Inquirex
 
       private
 
+      # Records requiredness from either spelling, rejecting a step that says
+      # both things at once. `required false` alongside `optional` agrees and is
+      # allowed — harmlessly redundant — but `required` with `optional` is a
+      # contradiction, and silently letting the last call win would hide it.
+      #
+      # @param keyword [Symbol] :required or :optional, for the error message
+      # @param value [Boolean] the resulting requiredness
+      # @return [void]
+      # @raise [Errors::DefinitionError] on contradictory declarations
+      def assign_requiredness(keyword, value)
+        if !@requiredness.nil? && @requiredness != value
+          raise Errors::DefinitionError,
+            "Step declares both required and optional with conflicting values " \
+            "(#{keyword} would make it #{value ? "required" : "optional"}); use one"
+        end
+
+        @requiredness = value
+        @required = value
+      end
+
       def pick_accumulator_shape(lookup:, per_selection:, per_unit:, flat:)
         provided = { lookup:, per_selection:, per_unit:, flat: }.compact
         if provided.size != 1

data/lib/inquirex/node.rb

@@ -40,6 +40,12 @@ module Inquirex
       enum multi_enum date email phone
     ].freeze
 
+    # Types for which {#min}, {#max} and {#step_size} carry meaning. Declaring
+    # a bound on anything else is a definition error rather than a silent
+    # no-op — a bounded `:string` almost always means the author picked the
+    # wrong type, and failing loudly is cheaper than shipping it.
+    BOUNDED_TYPES = %i[integer decimal currency].freeze
+
     attr_reader :id,
       :verb,
       :type,
@@ -51,6 +57,9 @@ module Inquirex
       :skip_if,
       :default,
       :required,
+      :min,
+      :max,
+      :step_size,
       :widget_hints,
       :accumulations
 
@@ -64,6 +73,9 @@ module Inquirex
       skip_if: nil,
       default: nil,
       required: true,
+      min: nil,
+      max: nil,
+      step_size: nil,
       widget_hints: nil,
       accumulations: [])
       @id = id.to_sym
@@ -75,12 +87,47 @@ module Inquirex
       @skip_if = skip_if
       @default = default
       @required = required ? true : false
+      @min = coerce_bound(min)
+      @max = coerce_bound(max)
+      @step_size = coerce_bound(step_size)
       @widget_hints = widget_hints&.freeze
       @accumulations = accumulations.freeze
       extract_options(options)
+      validate_bounds!
       freeze
     end
 
+    # Whether this step declares any numeric bound at all.
+    #
+    # @return [Boolean]
+    def bounded?
+      !@min.nil? || !@max.nil?
+    end
+
+    # Pulls a number inside this step's declared bounds.
+    #
+    # The wire format carries `min`/`max` so a renderer can *present* them, but
+    # an HTML number input does not stop a visitor typing past them and an LLM
+    # extraction has no notion of them at all. Every path that stores an answer
+    # for a bounded step goes through here, so the bound holds regardless of
+    # which client produced the value.
+    #
+    # @example
+    #   node.clamp(900)  # => 10, for a step declaring `max 10`
+    #
+    # @param value [Object] candidate answer
+    # @return [Object] the clamped Numeric, or the value unchanged when it is
+    #   not numeric or the step declares no bounds
+    def clamp(value)
+      return value unless bounded?
+      return value unless value.is_a?(Numeric)
+
+      clamped = value
+      clamped = @min if @min && clamped < @min
+      clamped = @max if @max && clamped > @max
+      clamped
+    end
+
     # @return [Boolean] true if this step collects input from the user
     def collecting?
       COLLECTING_VERBS.include?(@verb)
@@ -179,6 +226,9 @@ module Inquirex
         hash["skip_if"] = @skip_if.to_h if @skip_if
         hash["default"] = @default unless @default.nil? || @default.is_a?(Proc)
         hash["required"] = false unless @required
+        hash["min"] = @min unless @min.nil?
+        hash["max"] = @max unless @max.nil?
+        hash["step_size"] = @step_size unless @step_size.nil?
       elsif @text
         hash["text"] = @text
       end
@@ -215,6 +265,9 @@ module Inquirex
       default = hash["default"] || hash[:default]
       # Fetch chain (not ||) so an explicit false survives; absent key means required.
       required = hash.fetch("required") { hash.fetch(:required, true) }
+      min = hash["min"] || hash[:min]
+      max = hash["max"] || hash[:max]
+      step_size = hash["step_size"] || hash[:step_size]
       widget_data = hash["widget"] || hash[:widget]
       accumulate_data = hash["accumulate"] || hash[:accumulate]
 
@@ -235,6 +288,9 @@ module Inquirex
         skip_if:,
         default:,
         required:,
+        min:,
+        max:,
+        step_size:,
         widget_hints:,
         accumulations:
       )
@@ -242,6 +298,29 @@ module Inquirex
 
     private
 
+    # Numeric bounds arrive as Integers from Ruby DSL and as either Integer or
+    # Float from parsed JSON. Anything else — a String "10", a Symbol — is a
+    # definition error, not something to coerce quietly into 0.
+    def coerce_bound(value)
+      return nil if value.nil?
+      raise Errors::DefinitionError, "step #{@id}: numeric bound must be a number, got #{value.inspect}" unless value.is_a?(Numeric)
+
+      value
+    end
+
+    def validate_bounds!
+      return if @min.nil? && @max.nil? && @step_size.nil?
+
+      if @type && !BOUNDED_TYPES.include?(@type)
+        raise Errors::DefinitionError,
+          "step #{@id}: min/max/step_size only apply to #{BOUNDED_TYPES.join(", ")} steps, not #{@type}"
+      end
+
+      return unless @min && @max && @min > @max
+
+      raise Errors::DefinitionError, "step #{@id}: min (#{@min}) is greater than max (#{@max})"
+    end
+
     def extract_options(raw)
       case raw
       when Hash

data/lib/inquirex/safe_source/vocabulary.rb

@@ -278,6 +278,22 @@ module Inquirex
           # `{ optional: :literal }` mirrors `required(value = true)`: both bare
           # `required` and `required false` are real DSL.
           allow :step, :required, positional: { optional: :literal }
+          # `optional` is the inverse spelling of `required` and carries exactly
+          # the same authority — it sets the same field and serializes to the
+          # same `"required": false`. (The `optional:` key below is the argument
+          # schema's own word for "this positional may be omitted", unrelated to
+          # the verb being allowed here: both bare `optional` and `optional true`
+          # are real DSL.)
+          allow :step, :optional, positional: { optional: :literal }
+          # Numeric bounds are inert metadata in exactly the sense `required`
+          # is: Node stores them, `Node#clamp` reads them, and they serialize to
+          # plain numbers. `:literal` is the same value kind `default` already
+          # accepts, so nothing executable becomes expressible — a non-Numeric
+          # literal is refused by `Node#coerce_bound` at build time rather than
+          # by the scanner.
+          allow :step, :min, positional: %i[literal]
+          allow :step, :max, positional: %i[literal]
+          allow :step, :step_size, positional: %i[literal]
           allow :step, :skip_if, positional: %i[rule]
           allow :step, :transition, keywords: TRANSITION_KEYWORDS
           allow :step,

data/lib/inquirex/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.5
 platform: ruby
 authors:
 - Konstantin Gredeskoul