actionable-rb 1.9.0

data/lib/actionable/runner.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Executes an action instance's steps and produces the {Result}.
+  #
+  # The main loop runs inside {Actionable.catch_halt}, so a halting step
+  # (+throw Actionable::HALT+) unwinds out of the loop without running the
+  # remaining steps. Genuine exceptions are not caught — they propagate to the
+  # caller (decision D4). When no step recorded a result, the run auto-succeeds.
+  #
+  # After the main steps the runner picks the lifecycle hook category from the
+  # outcome (+on_success+ vs +on_failure+) and runs it, then the +always+ hooks
+  # (decision D2). Hooks are ordinary methods: they may record via the
+  # control-flow verbs, and a halting verb (+fail!+ / +skip!+ / +succeed!+ /
+  # +halt!+) has its result adopted, then stops the remaining hooks of its own
+  # phase: a halt in an outcome hook skips the rest of that category but the
+  # +always+ hooks still run (seeing the adopted result), and a halt in an
+  # +always+ hook skips the remaining +always+ hooks. The output is refreshed
+  # (re-captured and re-validated) after the main steps and after each hook
+  # (decision D6).
+  #
+  # When the action (or an enclosing measuring run) enables measurement, the
+  # runner records a {History} of every step — section, name, timing, result
+  # code, and nested child history (decision D10).
+  class Runner
+    # @param instance [Action] the action instance to run
+    def initialize(instance)
+      @instance = instance
+    end
+
+    # Run the action's steps and lifecycle hooks, returning the finalized result.
+    #
+    # @return [Result] the recorded result (or a fresh {Success} if none was
+    #   set), with its typed output and (when measuring) history assigned
+    def run
+      @measuring = @instance.class.measure_all? || @instance.class.measure_sample_hit? || Measurement.active?
+      @history = History.new if @measuring
+      measured { perform }
+      @result.history = @history if @measuring
+      @result
+    end
+
+    private
+
+    # Run the body, marking measurement active so nested runs cascade.
+    #
+    # @yield the body to run
+    # @yieldreturn [Object]
+    # @return [Object] the block's value
+    def measured(&)
+      return yield unless @measuring
+
+      Measurement.measuring(&)
+    end
+
+    # The main steps, then the outcome and always lifecycle hooks.
+    #
+    # @return [void]
+    def perform
+      Actionable.catch_halt { run_steps }
+      @result = instance_result || Success.new
+      refresh_output
+      run_lifecycle
+    end
+
+    # Run each declared step in order, skipping any whose guard opts out.
+    #
+    # @return [void]
+    def run_steps
+      @instance.class.steps.each { |step| call_step(:main, step) }
+    end
+
+    # Run the outcome-appropriate hooks then the +always+ hooks, each phase in
+    # its own halt catch: a hook's halt stops the remaining hooks of its phase
+    # only, so +always+ hooks run even after an outcome hook halts. The
+    # category is fixed by the post-main-steps outcome — it does not re-dispatch
+    # if a hook later flips the result.
+    #
+    # @return [void]
+    def run_lifecycle
+      section, hooks =
+        if @result.success?
+          [:success, @instance.class.success_hooks]
+        elsif @result.skipped?
+          [:skip, @instance.class.skip_hooks]
+        else
+          [:failure, @instance.class.failure_hooks]
+        end
+      Actionable.catch_halt { hooks.each { |hook| run_hook(section, hook) } }
+      Actionable.catch_halt { @instance.class.always_hooks.each { |hook| run_hook(:always, hook) } }
+    end
+
+    # Run one hook, then adopt any result it recorded and refresh the output.
+    # A hook that halts is caught here first so its result is adopted too, then
+    # the halt is re-thrown to stop the remaining hooks of the phase.
+    #
+    # @param section [Symbol]
+    # @param hook [Steps::Base]
+    # @return [void]
+    def run_hook(section, hook)
+      return if hook.skip?(@instance)
+
+      before = @instance.result
+      completed = false
+      Actionable.catch_halt do
+        record(section, hook) { hook.call(@instance) }
+        completed = true
+      end
+      @result = instance_result unless instance_result.equal?(before)
+      refresh_output
+      throw HALT unless completed
+    end
+
+    # Run one main step, skipping it when its guard opts out.
+    #
+    # @param section [Symbol]
+    # @param step [Steps::Base]
+    # @return [void]
+    def call_step(section, step)
+      return if step.skip?(@instance)
+
+      record(section, step) { step.call(@instance) }
+    end
+
+    # Time and record a step into the history when measuring; otherwise just run
+    # it. The result code is recorded only when the step changed the recorded
+    # result, so steps that merely set ivars carry a nil code.
+    #
+    # @param section [Symbol]
+    # @param step [Steps::Base]
+    # @return [void]
+    def record(section, step, &)
+      return yield unless @measuring
+
+      entry = History::Step.new(section: section, name: step.name, started_at: Time.now)
+      before = @instance.result
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        Measurement.recording(entry, &)
+      ensure
+        entry.duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        entry.code = instance_result&.code unless @instance.result.equal?(before)
+        @history << entry
+      end
+    end
+
+    # Capture, coerce, and attach the typed output (decision D6). Free-form
+    # actions (no schema) keep whatever output was recorded. With a schema,
+    # capture the declared-field ivars overlaid with any +succeed+ kwargs
+    # (kwargs win) and coerce them. Only a strict {Success} is validated — its
+    # output failing validation means it can't really have succeeded, so
+    # +@result+ becomes a +Failure(:invalid_output)+.
+    #
+    # A {Failure} or {Skipped} whose code declares its own output schema
+    # (decision D23) is built from its kwargs alone and validated the same way.
+    # Without one it carries an empty output under typed outcomes, and
+    # otherwise a best-effort, unvalidated capture into the success schema
+    # (decisions D6/D17). The failures the gem builds keep their output.
+    #
+    # @return [void]
+    def refresh_output
+      return refresh_success_output if @result.success?
+
+      if (schema = outcome_schema)
+        attach_validated(build_output(schema, outcome_attributes(schema)))
+      elsif @instance.class.typed_outcomes?
+        @result.output = {} unless gem_failure?
+      elsif (schema = @instance.class.output_schema) && !gem_failure?
+        attach_unvalidated(build_output(schema, captured_attributes(schema)))
+      end
+    end
+
+    # @return [void]
+    def refresh_success_output
+      schema = @instance.class.output_schema
+      return unless schema
+
+      attach_validated(build_output(schema, captured_attributes(schema)))
+    end
+
+    # Build the output struct and note on the result which fields the run
+    # actually set, so a parent absorbing this run copies only those (D3).
+    #
+    # @param schema [Class<FieldStruct::Base>]
+    # @param attrs [Hash{Symbol=>Object}]
+    # @return [FieldStruct::Base]
+    def build_output(schema, attrs)
+      @result.output_fields_set = attrs.keys
+      schema.new(**attrs)
+    end
+
+    # The result the action instance recorded, refusing anything else stored
+    # in the reserved +@result+ ivar with a clear error instead of a deep
+    # +NoMethodError+.
+    #
+    # @raise [DefinitionError] when +@result+ holds something other than a {Result}
+    # @return [Result, nil]
+    def instance_result
+      result = @instance.result
+      return result if result.nil? || result.is_a?(Result)
+
+      raise DefinitionError,
+        "#{@instance.class.name || "action"} set @result to a #{result.class}; " \
+        '@result is reserved for the run\'s result, so rename the instance variable'
+    end
+
+    # Attach +output+ when it is valid; otherwise the run ends as a
+    # +Failure(:invalid_output)+ carrying it.
+    #
+    # @param output [FieldStruct::Base]
+    # @return [void]
+    def attach_validated(output)
+      output.valid? ? (@result.output = output) : (@result = invalid_output_failure(output))
+    end
+
+    # Attach a best-effort output to a failure or skip without validating it
+    # (decisions D6/D17). Assigning a struct makes the result validate it, which
+    # would add an +output+ error, so only the errors the result already had
+    # are kept.
+    #
+    # @param output [FieldStruct::Base]
+    # @return [void]
+    def attach_unvalidated(output)
+      kept = Array(@result.errors.to_h[:output]).dup
+      @result.output = output
+      @result.errors.clear(:output)
+      kept.each { |message| @result.errors.add(:output, message) }
+    end
+
+    # @return [Class<FieldStruct::Base>, nil] the output schema the skip or
+    #   failure's code declares (decision D23), if any
+    def outcome_schema
+      klass = @instance.class
+      @result.skipped? ? klass.skip_output_schema(@result.code) : klass.failure_output_schema(@result.code)
+    end
+
+    # A skip or failure's output fields, from the kwargs it was recorded with,
+    # never from instance variables (decision D23). After a hook refresh the
+    # output is already the struct, so its own attributes are reused, limited
+    # to the fields the kwargs set so the set-fields marker stays true.
+    #
+    # @param schema [Class<FieldStruct::Base>]
+    # @return [Hash{Symbol=>Object}]
+    def outcome_attributes(schema)
+      recorded = @result.output
+      if recorded.is_a?(FieldStruct::Base)
+        set = @result.output_fields_set
+        recorded = set ? recorded.attributes.slice(*set) : recorded.attributes
+      end
+      recorded.is_a?(Hash) ? recorded.slice(*schema.attribute_names) : {}
+    end
+
+    # @return [Boolean] whether the result is a failure the gem itself built
+    #   ({Action::GEM_FAILURE_CODES}), whose output is left as it is
+    def gem_failure?
+      @result.failure? && Action::GEM_FAILURE_CODES.include?(@result.code)
+    end
+
+    # Declared-field ivars from the action instance, overlaid with the recorded
+    # +succeed+ / +skip+ kwargs, kwargs winning on conflict.
+    #
+    # @param schema [Class<FieldStruct::Base>]
+    # @return [Hash{Symbol=>Object}]
+    def captured_attributes(schema)
+      attrs = {}
+      schema.attribute_names.each do |name|
+        ivar = :"@#{name}"
+        attrs[name] = @instance.instance_variable_get(ivar) if @instance.instance_variable_defined?(ivar)
+      end
+      attrs.merge(recorded_overrides.slice(*schema.attribute_names))
+    end
+
+    # The +succeed+ / +skip+ kwargs recorded with the current result. They sit
+    # on +@result.output+ as a Hash only until the first refresh replaces it
+    # with the struct, so they are kept here to overlay every later refresh
+    # (after each hook) as well.
+    #
+    # @return [Hash{Symbol=>Object}]
+    def recorded_overrides
+      if @result.output.is_a?(Hash)
+        @overrides_owner = @result
+        @overrides = @result.output
+      end
+      @overrides_owner.equal?(@result) ? @overrides : {}
+    end
+
+    # @param output [FieldStruct::Base] the invalid output struct
+    # @return [Failure] code +:invalid_output+, with the output's validation
+    #   errors copied onto the failure and the (invalid) output attached
+    def invalid_output_failure(output)
+      failure = Failure.new(
+        code: :invalid_output,
+        message: 'output failed validation',
+        metadata: @instance.class.declared_failures.fetch(:invalid_output, {})
+      ).absorb_errors_from(output)
+      failure.output = output
+      failure
+    end
+  end
+end

data/lib/actionable/steps/action.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Actionable
+  module Steps
+    # A step that runs another action as part of this one (decision D3,
+    # triggered by an action +Class+ step argument).
+    #
+    # +:input+ threads named parent instance variables into the child's +.run+;
+    # +:expose+ limits which of the child's outputs are absorbed back as parent
+    # instance variables (default: all). A child failure fails the parent with
+    # the child's code, message, errors and metadata, and halts the remaining
+    # steps.
+    class Action < Base
+      # Run the nested action, threading input in and absorbing output back.
+      #
+      # @param instance [Actionable::Action] the parent action instance
+      # @return [void]
+      def call(instance)
+        child = name.run(**input_kwargs(instance))
+
+        # Attach the child's history to the open step record (no-op unless the
+        # parent run is measuring), before any failure propagation unwinds.
+        Measurement.open_step&.nested = child.history if child.history.is_a?(History)
+
+        if child.failure?
+          # Propagate the child's failure onto the parent and halt. Not through
+          # +fail!+: splatting the errors into a keyword list lost the metadata
+          # and let an error keyed like a keyword the parent's +fail+ takes bind
+          # to it (decision D20).
+          instance.__send__(:adopt_failure!, child)
+        else
+          absorb(instance, child)
+        end
+      end
+
+      # @return [Symbol]
+      def kind
+        :action
+      end
+
+      private
+
+      # @param instance [Actionable::Action]
+      # @return [Hash{Symbol=>Object}] +{ name => @name }+ for each +:input+ name
+      def input_kwargs(instance)
+        Array(options[:input]).to_h { |name| [name, instance.instance_variable_get(:"@#{name}")] }
+      end
+
+      # Copy the child's exposed output fields onto the parent as instance
+      # variables, so the parent's later steps and output capture see them.
+      # Only fields the child actually set are copied: a field it left nil or
+      # at its default must not overwrite the parent's value.
+      #
+      # @param instance [Actionable::Action]
+      # @param child [Result]
+      # @return [void]
+      def absorb(instance, child)
+        data = output_hash(child.output)
+        set = child.output_fields_set
+        data = data.slice(*set) if set && child.output.is_a?(FieldStruct::Base)
+        exposed = options.key?(:expose) ? data.slice(*Array(options[:expose])) : data
+        exposed.each { |field, value| instance.instance_variable_set(:"@#{field}", value) }
+      end
+
+      # @param output [FieldStruct::Base, Hash, Object]
+      # @return [Hash{Symbol=>Object}] the child output as a plain hash
+      def output_hash(output)
+        case output
+        when FieldStruct::Base then output.attributes
+        when Hash then output
+        else {}
+        end
+      end
+    end
+  end
+end

data/lib/actionable/steps/base.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Namespace for the concrete step types an action's pipeline is built from
+  # (decision D3): {Steps::Method} now, {Steps::Action} and {Steps::Case} later.
+  module Steps
+    # Shared behavior for every step: a +name+, an +options+ hash, value
+    # identity for Set deduplication (keyed by +[type, name]+, decision D2),
+    # and the +:if+ / +:unless+ skip logic. Subclasses implement {#call}.
+    #
+    # @abstract Subclass and implement {#call}.
+    class Base
+      # @return [Object] the step's name — a Symbol for a {Steps::Method},
+      #   an action Class for a {Steps::Action}
+      attr_reader :name
+
+      # @return [Hash{Symbol=>Object}] the declared step options (e.g. +:if+,
+      #   +:unless+, and step-type-specific keys)
+      attr_reader :options
+
+      # @param name [Object] the step name (see {#name})
+      # @param options [Object] step options
+      def initialize(name, **options)
+        @name = name
+        @options = options
+      end
+
+      # Run the step against an action instance.
+      #
+      # @param _instance [Object] the action instance the step runs against
+      # @raise [NotImplementedError] always — concrete step types override this
+      # @return [void]
+      def call(_instance)
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+
+      # Instance method names this step needs the action to implement, used by
+      # the run-start definition guard (decision D18). None for the base; concrete
+      # types that call instance methods override this.
+      #
+      # @return [Array<Symbol>]
+      def required_methods
+        []
+      end
+
+      # Instance methods whose bodies run as this step, for the recording-verb
+      # position check (owner ruling R5): not guards, not a case step's value
+      # source. None for the base; a nested action is checked on its own run.
+      #
+      # @return [Array<Symbol>]
+      def body_methods
+        []
+      end
+
+      # @return [Symbol] a short tag identifying the step type, for introspection
+      #   (+Actionable::Action.describe+). Concrete types override it.
+      def kind
+        :step
+      end
+
+      # Whether this step should be skipped for the given instance, per its
+      # +:if+ / +:unless+ guards. A guard is a Symbol naming a (possibly
+      # private) instance method, or a callable invoked with the instance.
+      # When both guards are present, either one asking to skip wins.
+      #
+      # @param instance [Object] the action instance to evaluate guards against
+      # @return [Boolean]
+      def skip?(instance)
+        return true if options.key?(:if) && !evaluate_guard(options[:if], instance)
+        return true if options.key?(:unless) && evaluate_guard(options[:unless], instance)
+
+        false
+      end
+
+      # Value identity: same concrete class AND same name. This keys steps in
+      # the per-action Set so a redeclared step dedups (decision D2).
+      #
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+        other.instance_of?(self.class) && name == other.name
+      end
+      alias eql? ==
+
+      # @return [Integer] consistent with {#==}, so steps work as Set members
+      def hash
+        [self.class, name].hash
+      end
+
+      private
+
+      # Resolve a guard against the instance. A Symbol/String names an instance
+      # method (called via +__send__+, so private predicates work); anything
+      # else is treated as a callable receiving the instance.
+      #
+      # @param guard [Symbol, String, #call]
+      # @param instance [Object]
+      # @return [Boolean]
+      def evaluate_guard(guard, instance)
+        case guard
+        when Symbol, String then instance.__send__(guard)
+        else guard.call(instance)
+        end
+      end
+    end
+  end
+end

data/lib/actionable/steps/case.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Actionable
+  module Steps
+    # A step that branches to one of several targets based on a value
+    # (decision D3, declared with +case_step+). The switch value is read from
+    # the action via the named method; each branch's target is an ordinary step
+    # (a method or a nested action), so branches compose like any other step.
+    #
+    #   case_step :status do
+    #     on 'active',          :handle_active
+    #     on %w[trial grace],   :handle_trial      # Array membership
+    #     on(/\A4\d\d\z/,       :handle_client_err # Regexp
+    #     default               :handle_unknown
+    #   end
+    class Case < Base
+      # Collects +on+/+default+ branch declarations inside a +case_step+ block.
+      class Builder
+        # @return [Array<Array(Object, Steps::Base)>] ordered [match, step] pairs
+        attr_reader :branches
+        # @return [Steps::Base, nil] the fallback step, if +default+ was declared
+        attr_reader :default_step
+
+        def initialize
+          @branches = []
+          @default_step = nil
+        end
+
+        # Register a branch. +value+ matches the switch value by +==+, by
+        # +Regexp#match?+ when it is a Regexp, or by membership when it is an
+        # Array. +target+ is any step target (method name or nested action).
+        #
+        # @param value [Object, Regexp, Array]
+        # @param target [Symbol, String, Class<Actionable::Action>]
+        # @param options [Object] step options for the target (+:if+ / +:unless+
+        #   guard the branch: a matched branch whose guard opts out does nothing)
+        # @return [void]
+        def on(value, target, **options)
+          @branches << [value, Steps.build(target, **options)]
+        end
+
+        # Register the fallback branch, run when no +on+ branch matches.
+        #
+        # @param target [Symbol, String, Class<Actionable::Action>]
+        # @param options [Object] step options for the target
+        # @return [void]
+        def default(target, **options)
+          @default_step = Steps.build(target, **options)
+        end
+      end
+
+      # Build a case step from a +case_step+ declaration.
+      #
+      # @param value_source [Symbol, String] the method whose value is switched on
+      # @param options [Object] step options (e.g. +:if+, +:unless+)
+      # @yield the branch declarations (+on+ / +default+)
+      # @return [Case]
+      def self.define(value_source, **options, &block)
+        builder = Builder.new
+        builder.instance_eval(&block)
+        new(value_source, builder.branches, builder.default_step, **options)
+      end
+
+      # @param value_source [Symbol, String] the method whose value is switched on
+      # @param branches [Array<Array(Object, Steps::Base)>] ordered [match, step] pairs
+      # @param default_step [Steps::Base, nil] the fallback step
+      # @param options [Object] step options
+      def initialize(value_source, branches, default_step, **options)
+        super(value_source, **options)
+        @branches = branches
+        @default_step = default_step
+      end
+
+      # Evaluate the switch value and run the first matching branch (or the
+      # default). No-op when nothing matches and no default was declared.
+      #
+      # The branch is chosen by value alone; its +:if+ / +:unless+ guards then
+      # decide whether its target runs, exactly as for a plain step. A matched
+      # branch whose guard opts out is a no-op: it does not fall through to a
+      # later branch or to the default.
+      #
+      # @param instance [Actionable::Action]
+      # @return [void]
+      def call(instance)
+        value = instance.__send__(name) # private, like step methods
+        step = match(value) || @default_step
+        step.call(instance) unless step.nil? || step.skip?(instance)
+      end
+
+      # @return [Array<Symbol>] the switch-value method plus every branch
+      #   target's required methods
+      def required_methods
+        ([name] + branch_steps.flat_map(&:required_methods)).uniq
+      end
+
+      # @return [Array<Symbol>] every branch target's body methods (never the
+      #   switch-value method, which only returns the value)
+      def body_methods
+        branch_steps.flat_map(&:body_methods).uniq
+      end
+
+      # @return [Symbol]
+      def kind
+        :case
+      end
+
+      private
+
+      # @return [Array<Steps::Base>] every branch's step, the default included
+      def branch_steps
+        steps = @branches.map(&:last)
+        steps << @default_step if @default_step
+        steps
+      end
+
+      # @param value [Object] the switch value
+      # @return [Steps::Base, nil] the first matching branch's step
+      def match(value)
+        @branches.each { |branch_value, step| return step if ValueMatch.matches?(branch_value, value) }
+        nil
+      end
+    end
+  end
+end

data/lib/actionable/steps/method.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Actionable
+  module Steps
+    # A step that calls an instance method on the action (decision D3,
+    # triggered by a Symbol/String step argument).
+    class Method < Base
+      # @param name [Symbol, String] the instance method to call; normalized
+      #   to a Symbol
+      # @param options [Object] step options (e.g. +:if+, +:unless+)
+      def initialize(name, **options)
+        super(name.to_sym, **options)
+      end
+
+      # Invoke the named method on the instance.
+      #
+      # @param instance [Object] the action instance
+      # @return [Object] the method's return value
+      def call(instance)
+        instance.__send__(name) # private step methods work, like guards
+      end
+
+      # @return [Array<Symbol>] the instance method this step calls
+      def required_methods
+        [name]
+      end
+
+      # @return [Array<Symbol>] the instance method whose body is this step
+      def body_methods
+        [name]
+      end
+
+      # @return [Symbol]
+      def kind
+        :method
+      end
+    end
+  end
+end

data/lib/actionable/steps.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Actionable
+  module Steps
+    # Build the right step type from a +step+ declaration's target, inferring
+    # the type from the argument (decision D2): a Symbol/String becomes a
+    # {Steps::Method}, an action +Class+ becomes a {Steps::Action}. The case
+    # block type ({Steps::Case}) joins in a later slice.
+    #
+    # @param target [Symbol, String, Class<Actionable::Action>] the step target
+    # @param options [Object] step options (e.g. +:if+, +:unless+,
+    #   and for action steps +:input+ / +:expose+)
+    # @return [Steps::Base] the constructed step
+    # @raise [ArgumentError] when the target's type is not supported
+    def self.build(target, **options)
+      case target
+      when Symbol, String then Method.new(target, **options)
+      when Class
+        raise ArgumentError, "unsupported step target: #{target.inspect}" unless target < Actionable::Action
+
+        Action.new(target, **options)
+      else
+        raise ArgumentError, "unsupported step target: #{target.inspect}"
+      end
+    end
+  end
+end

data/lib/actionable/value_match.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Shared branch-value matching for the two places Actionable dispatches on a
+  # value: case steps (decision D3) and discriminated input (decision D19). A
+  # branch value matches by Array membership, by +Regexp#match?+ against the
+  # value's string form, or by +==+.
+  module ValueMatch
+    module_function
+
+    # @param branch_value [Object, Array, Regexp] the declared branch matcher
+    # @param value [Object] the runtime value being dispatched on
+    # @return [Boolean] whether +value+ matches +branch_value+
+    def matches?(branch_value, value)
+      case branch_value
+      when Array then branch_value.include?(value)
+      when Regexp then branch_value.match?(value.to_s)
+      else branch_value == value
+      end
+    end
+  end
+end