actionable-rb 1.9.0

data/lib/actionable/rspec/stubs.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Actionable
+  module RSpec
+    # Helpers mixed into example groups by +actionable/rspec+ that stub an
+    # action's +.run+ to return a real {Success} / {Failure} built from a hash,
+    # so callers can assert on +result.code+/+output+/+errors+ without executing
+    # the action (decision D12).
+    #
+    # +allow_*+ permits the call (a stub); +stub_*+ also sets a call expectation
+    # (a mock, verified on the example) — mirroring RSpec's allow/expect split.
+    #
+    # A stubbed failure of an action that declares failures with
+    # {Actionable::Action.fails} carries the declared metadata (and message,
+    # when none is given) for its code, and a code the action doesn't declare
+    # raises +ArgumentError+, so a stub can't return what the action never
+    # could (decision D20). A stubbed skip follows {Actionable::Action.skips}
+    # the same way (decision D21), the default +:skipped+ included.
+    module Stubs
+      # @param action_class [Class<Actionable::Action>] the action whose +.run+ is stubbed
+      # @param opts [Object] {#actionable_success_result}'s keywords (+message:+, +output:+, +errors:+)
+      # @return [Success] the stubbed result
+      def allow_actionable_success(action_class, **opts)
+        allow_run(action_class, actionable_success_result(**opts))
+      end
+
+      # @param action_class [Class<Actionable::Action>] the action whose +.run+ is stubbed
+      # @param opts [Object] {#actionable_success_result}'s keywords (+message:+, +output:+, +errors:+)
+      # @return [Success] the stubbed result
+      def stub_actionable_success(action_class, **opts)
+        expect_run(action_class, actionable_success_result(**opts))
+      end
+
+      # @param action_class [Class<Actionable::Action>] the action whose +.run+ is stubbed
+      # @param opts [Object] {#actionable_failure_result}'s keywords; +code:+ defaults to +:error+
+      # @return [Failure] the stubbed result
+      # @raise [ArgumentError] when the action declares failures but not the code
+      def allow_actionable_failure(action_class, **opts)
+        allow_run(action_class, declared_failure_result(action_class, **opts))
+      end
+
+      # @param action_class [Class<Actionable::Action>] the action whose +.run+ is stubbed
+      # @param opts [Object] {#actionable_failure_result}'s keywords; +code:+ defaults to +:error+
+      # @return [Failure] the stubbed result
+      # @raise [ArgumentError] when the action declares failures but not the code
+      def stub_actionable_failure(action_class, **opts)
+        expect_run(action_class, declared_failure_result(action_class, **opts))
+      end
+
+      # @param action_class [Class<Actionable::Action>] the action whose +.run+ is stubbed
+      # @param opts [Object] {#actionable_skip_result}'s keywords; +code:+ defaults to +:skipped+
+      # @return [Skipped] the stubbed result
+      # @raise [ArgumentError] when the action declares skips but not the code
+      def allow_actionable_skip(action_class, **opts)
+        allow_run(action_class, declared_skip_result(action_class, **opts))
+      end
+
+      # @param action_class [Class<Actionable::Action>] the action whose +.run+ is stubbed
+      # @param opts [Object] {#actionable_skip_result}'s keywords; +code:+ defaults to +:skipped+
+      # @return [Skipped] the stubbed result
+      # @raise [ArgumentError] when the action declares skips but not the code
+      def stub_actionable_skip(action_class, **opts)
+        expect_run(action_class, declared_skip_result(action_class, **opts))
+      end
+
+      # Build a real {Success} from a hash (no stubbing).
+      #
+      # @param message [String, nil]
+      # @param output [Hash{Symbol=>Object}, FieldStruct::Base]
+      # @param errors [Hash{Symbol=>String, Array<String>}]
+      # @return [Success]
+      def actionable_success_result(message: nil, output: {}, errors: {})
+        apply_errors(Actionable::Success.new(message: message, output: output), errors)
+      end
+
+      # Build a real {Failure} from a hash (no stubbing).
+      #
+      # @param code [Symbol]
+      # @param message [String, nil]
+      # @param output [Hash{Symbol=>Object}, FieldStruct::Base]
+      # @param errors [Hash{Symbol=>String, Array<String>}]
+      # @param metadata [Hash{Symbol=>Object}] the failure's per-code metadata
+      # @return [Failure]
+      def actionable_failure_result(code: :error, message: nil, output: {}, errors: {}, metadata: {})
+        failure = Actionable::Failure.new(code: code, message: message, output: output, metadata: metadata)
+        apply_errors(failure, errors)
+      end
+
+      # Build a real {Skipped} from a hash (no stubbing).
+      #
+      # @param code [Symbol]
+      # @param message [String, nil]
+      # @param output [Hash{Symbol=>Object}, FieldStruct::Base]
+      # @param metadata [Hash{Symbol=>Object}] the skip's per-code metadata
+      # @return [Skipped]
+      def actionable_skip_result(code: :skipped, message: nil, output: {}, metadata: {})
+        Actionable::Skipped.new(code: code, message: message, output: output, metadata: metadata)
+      end
+
+      private
+
+      # A {Failure} for +action_class+: the declared metadata and message for
+      # its code, or a refusal when the action declares failures but not it.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param code [Symbol, String]
+      # @param opts [Object] the rest of {#actionable_failure_result}'s keywords
+      # @raise [ArgumentError] when the action declares failures but not +code+
+      # @return [Failure]
+      def declared_failure_result(action_class, code: :error, **opts)
+        unless action_class.allows_failure_code?(code)
+          raise ArgumentError, Actionable::RSpec.undeclared_code_message(action_class, code)
+        end
+
+        declaration = action_class.failure_declarations.fetch(code.to_sym, {message: nil, metadata: {}})
+        opts[:message] ||= declaration[:message]
+        actionable_failure_result(code: code, metadata: declaration[:metadata], **opts)
+      end
+
+      # A {Skipped} for +action_class+: the declared metadata and message for
+      # its code, or a refusal when the action declares skips but not it.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param code [Symbol, String]
+      # @param opts [Object] the rest of {#actionable_skip_result}'s keywords
+      # @raise [ArgumentError] when the action declares skips but not +code+
+      # @return [Skipped]
+      def declared_skip_result(action_class, code: :skipped, **opts)
+        unless action_class.allows_skip_code?(code)
+          raise ArgumentError, Actionable::RSpec.undeclared_code_message(action_class, code, outcome: :skip)
+        end
+
+        declaration = action_class.skip_declarations.fetch(code.to_sym, {message: nil, metadata: {}})
+        opts[:message] ||= declaration[:message]
+        actionable_skip_result(code: code, metadata: declaration[:metadata], **opts)
+      end
+
+      # Permit +action_class.run+, answering +result+ as a real run would.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param result [Result]
+      # @return [Result] the result the stub answers
+      def allow_run(action_class, result)
+        result = as_action_result(action_class, result)
+        allow(action_class).to receive(:run) { stubbed_run(action_class, result) }
+        result
+      end
+
+      # Expect +action_class.run+ (verified on the example), answering +result+
+      # as a real run would.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param result [Result]
+      # @return [Result] the result the stub answers
+      def expect_run(action_class, result)
+        result = as_action_result(action_class, result)
+        expect(action_class).to receive(:run) { stubbed_run(action_class, result) }
+        result
+      end
+
+      # The stubbed result as a real run would return it (decision D23): its
+      # output shaped by the schema it is held to, then as the action's own
+      # result class when it has typed outcomes.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param result [Result]
+      # @return [Result]
+      def as_action_result(action_class, result)
+        shape_output(action_class, result)
+        action_class.__send__(:typed_result, result)
+      end
+
+      # Mirror the runner: output for a code with a schema becomes that schema
+      # (refused when it breaks it, since a real run would end as
+      # +invalid_output+ instead), and under typed outcomes a code without one
+      # carries an empty output (refused when output is given, as a real run
+      # refuses it). The gem's own failure codes keep what they are given.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param result [Result] updated in place
+      # @raise [ArgumentError] when the output breaks what a real run allows
+      # @return [void]
+      def shape_output(action_class, result)
+        schema = stubbed_output_schema(action_class, result)
+        return result.output = build_stubbed_output(action_class, result, schema) if schema
+        return unless action_class.typed_outcomes? && !result.success?
+        return if result.failure? && Actionable::Action::GEM_FAILURE_CODES.include?(result.code)
+
+        unless result.output.respond_to?(:empty?) && result.output.empty?
+          raise ArgumentError, "#{action_class.name || "action"} output for #{result.code.inspect}, which declares no " \
+                               'output schema; a real run refuses it'
+        end
+        result.output = {}
+      end
+
+      # @return [Class<FieldStruct::Base>, nil] the schema the result's output
+      #   is held to: its code's, or the success schema under typed outcomes
+      # @param action_class [Class<Actionable::Action>]
+      # @param result [Result]
+      def stubbed_output_schema(action_class, result)
+        return action_class.skip_output_schema(result.code) if result.skipped?
+        return action_class.failure_output_schema(result.code) if result.failure?
+
+        action_class.output_schema if action_class.typed_outcomes?
+      end
+
+      # The stub's output as an instance of +schema+, built from the fields of
+      # +result+'s output that the schema declares.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param result [Result]
+      # @param schema [Class<FieldStruct::Base>]
+      # @raise [ArgumentError] when the output breaks +schema+
+      # @return [FieldStruct::Base]
+      def build_stubbed_output(action_class, result, schema)
+        given = result.output.is_a?(FieldStruct::Base) ? result.output.attributes : result.output.to_h
+        given = given.slice(*schema.attribute_names)
+        # A parent absorbs only the fields a run set, so a stub sets the ones it was given.
+        result.output_fields_set = given.keys
+        output = schema.new(**given)
+        return output if output.valid?
+
+        raise ArgumentError, "#{action_class.name || "action"} output for #{result.code.inspect} breaks its schema " \
+                             "(#{output.errors.full_messages.join(", ")}); a real run would end as invalid_output"
+      end
+
+      # The stub's response: +result+, noted as a stubbed run when outcome
+      # coverage is loaded (decision D22), so a report can tell an outcome
+      # only ever stubbed from one never reached at all.
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param result [Result]
+      # @return [Result] +result+
+      def stubbed_run(action_class, result)
+        Actionable::Coverage.record_stub(action_class, result) if defined?(Actionable::Coverage)
+        result
+      end
+
+      # Add +errors+ to +result+'s errors.
+      #
+      # @param result [Result]
+      # @param errors [Hash{Symbol=>String, Array<String>}]
+      # @return [Result] +result+
+      def apply_errors(result, errors)
+        errors.each { |field, messages| Array(messages).each { |message| result.errors.add(field, message) } }
+        result
+      end
+    end
+  end
+end

data/lib/actionable/rspec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Optional RSpec integration (decision D12). Load it explicitly with
+# `require 'actionable/rspec'` (typically in spec_helper, after rspec). Never
+# loaded by the core entry point.
+require_relative '../actionable' # ensure the core is loaded (self-contained entry)
+require_relative 'rspec/matchers'
+require_relative 'rspec/stubs'
+
+module Actionable
+  # RSpec matchers and stubs for actions (decision D12).
+  module RSpec
+    # The refusal for a stub, +and_fail+ or +and_skip+ naming a code an action
+    # that declares failures (decision D20) or skips (decision D21) doesn't
+    # declare.
+    #
+    # @param action_class [Class<Actionable::Action>]
+    # @param code [Symbol, String]
+    # @param outcome [:failure, :skip] which declarations the code was checked against
+    # @return [String]
+    def self.undeclared_code_message(action_class, code, outcome: :failure)
+      if outcome == :skip
+        declared = action_class.declared_skips.keys.map(&:inspect).join(', ')
+        return "#{action_class.name || "action"} does not declare skip #{code.to_sym.inspect} " \
+               "(declared: #{declared}); a stub or and_skip with it tests a skip the action can never return"
+      end
+
+      declared = action_class.declared_failures.keys.map(&:inspect).join(', ')
+      "#{action_class.name || "action"} does not declare #{code.to_sym.inspect} (declared: #{declared}); " \
+        'a stub or and_fail with it tests a failure the action can never return'
+    end
+  end
+end
+
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include Actionable::RSpec::Matchers
+    config.include Actionable::RSpec::Stubs
+  end
+end

data/lib/actionable/rubocop/config.yml

@@ -0,0 +1,8 @@
+Actionable/VerbNotLast:
+  Description: 'A plain fail/fail_with/skip/succeed must be the last expression of its step or hook method.'
+  Enabled: true
+  # Subclasses of these (or of a class in the same file that reaches one) are
+  # checked; any other class, e.g. a dry-transaction with its own `step`, is not.
+  ActionBaseClasses:
+    - Actionable::Action
+    - ApplicationAction

data/lib/actionable/rubocop/cop/actionable/verb_not_last.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Actionable
+      # A plain recording verb (+fail+ / +fail_with+ / +skip+ / +succeed+) must
+      # be the last expression of its step or hook method: it records the
+      # outcome and keeps running, so code after it still runs (owner rulings
+      # R5, R10). The
+      # same rules as the gem's first-run check, from the same analyzer
+      # (+Actionable::VerbPosition+); USAGE (Control flow) has the table.
+      #
+      # It sees one file: a class whose superclass is an action base (see
+      # +ActionBaseClasses+) and that declares +step+ / +case_step+, and the
+      # methods that class names in a step, case-step branch or hook
+      # declaration. A class with another +step+ DSL (dry-transaction) is
+      # left alone.
+      #
+      # +ActionBaseClasses+ (default +Actionable::Action+, +ApplicationAction+)
+      # lists the base classes by full name; a class defined in the same file
+      # whose superclass chain reaches one counts too. A superclass name
+      # resolves lexically, as Ruby looks it up, so two same-named classes
+      # in different modules are told apart.
+      #
+      # @example
+      #   # bad
+      #   def charge
+      #     fail :card_expired if card.expired?
+      #     notify
+      #   end
+      #
+      #   # good
+      #   def charge
+      #     fail! :card_expired if card.expired?
+      #     notify
+      #   end
+      #
+      #   # good
+      #   def charge
+      #     notify
+      #     fail :card_expired if card.expired?
+      #   end
+      class VerbNotLast < Base
+        # @return [String]
+        MSG = '`%<verb>s` records the outcome and keeps running, and more code runs after it: ' \
+              "use `%<verb>s!` to stop here, or make it the method's last expression."
+
+        # @return [void]
+        def on_new_investigation
+          result = ::Prism.parse(processed_source.raw_source)
+          return unless result.errors.empty?
+
+          base_classes = Array(cop_config.fetch('ActionBaseClasses', ::Actionable::VerbPosition::ACTION_BASE_CLASSES))
+          ::Actionable::VerbPosition.declared_step_offenses(result.value, base_classes: base_classes).each do |offense|
+            range = Parser::Source::Range.new(processed_source.buffer, offense.start_character, offense.end_character)
+            add_offense(range, message: format(MSG, verb: offense.verb))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/actionable/rubocop/plugin.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Actionable
+  # The lint_roller plugin RuboCop >= 1.72 loads for
+  # +plugins: [{actionable-rb: {require_path: actionable/rubocop}}]+ (the gemspec
+  # names it in +default_lint_roller_plugin+). It enables
+  # +Actionable/VerbNotLast+ through +config.yml+ beside this file.
+  class RubocopPlugin < LintRoller::Plugin
+    # @return [LintRoller::About]
+    def about
+      LintRoller::About.new(
+        name: 'actionable-rb', version: VERSION, homepage: 'https://github.com/Paymentbox-com/actionable',
+        description: 'Actionable/VerbNotLast: a plain fail/fail_with/skip/succeed must end its step or hook method.'
+      )
+    end
+
+    # @param context [LintRoller::Context]
+    # @return [Boolean]
+    def supported?(context)
+      context.engine == :rubocop
+    end
+
+    # @param _context [LintRoller::Context]
+    # @return [LintRoller::Rules]
+    def rules(_context)
+      LintRoller::Rules.new(type: :path, config_format: :rubocop, value: Pathname.new(__dir__).join('config.yml'))
+    end
+  end
+end

data/lib/actionable/rubocop.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The opt-in RuboCop integration: the +Actionable/VerbNotLast+ cop (owner
+# ruling R5). Never loaded by +require 'actionable'+; RuboCop loads it from
+# a project's +.rubocop.yml+:
+#
+#   plugins:
+#     - actionable-rb:
+#         require_path: actionable/rubocop
+#
+# or, on RuboCop < 1.72, +require: [actionable/rubocop]+. RuboCop depends on
+# Prism, so the cop always has it. Loads only the rule analyzer, not the gem.
+require 'rubocop'
+require 'prism'
+require_relative 'version'
+require_relative 'verb_position'
+require_relative 'rubocop/cop/actionable/verb_not_last'
+
+begin
+  require 'lint_roller' # RuboCop >= 1.72's plugin API
+rescue LoadError
+  nil
+else
+  require_relative 'rubocop/plugin'
+end