thunderoperation 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45776abcd16980536bbd63b5bb0b5f67c17103b990408ea68673c1ccb3b5fec2
+  data.tar.gz: a4965001230ededf0ee43cd9ddcead9be3fc6bad008fd7fac0cc2328be98d5c8
+SHA512:
+  metadata.gz: 1c544048645185dbcaf0fc93fe2364e8361a23e7a0cd9850933dcdc5504dff09d5fa026c51f8a4e18f8788bfd00fed687d5a1c90ffe52c4986b9b5f73d554dd6
+  data.tar.gz: 9c38b5e95bed8425e73ebfb4dc4b335808849d693ba605f5498e83795dbc13bda60ce68d11c1d1a362eddb156b1f8403317ba143deb2a890a149b14de15313db

data/README.md

@@ -0,0 +1,3 @@
+# thunderoperation
+
+Operations engine: `param`, `flow`, `steps`, `returns` and adapters. Ported from the old thunderbolt (`lib/thunderbolt/operations` at d75314d).

data/config/default.yml

@@ -0,0 +1,11 @@
+# WARN: AI MADE
+# Defaults for every project that loads the thunderoperation cops (require: thunderoperation/rubocop), merged over
+# RuboCop's own defaults; a project's .rubocop.yml still overrides them.
+
+# `flow do ... end` and `steps do ... end` hold the whole flow and every step of an operation, so their length is the
+# operation's, not a block's.
+Metrics/BlockLength:
+  AllowedMethods:
+    - refine # RuboCop's default
+    - flow
+    - steps

data/lib/rubocop/cop/thunderoperation/call_handlers.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # Inside `Operation.call(...) do ... end` only `success { |result| }` and `failure { |result| }` belong,
+      # each with a block, each at most once. Anything else runs against the handlers collector, not the operation.
+      class CallHandlers < Base
+        include OperationHelpers
+
+        HANDLERS = %i[success failure].freeze
+        UNEXPECTED_MSG = 'Only `success` and `failure` handlers belong in a `call` block.'
+        BLOCK_MSG = '`%<handler>s` handler needs a block.'
+        DUPLICATE_MSG = '`%<handler>s` handler is declared more than once.'
+
+        def on_block(node)
+          return unless call_with_handlers?(node) && inside_operation?(node)
+
+          seen = []
+          block_statements(node).each do |statement|
+            handler = handler_name(statement)
+            next add_offense(statement, message: UNEXPECTED_MSG) unless handler
+            next add_offense(statement, message: format(BLOCK_MSG, handler:)) unless statement.block_type?
+
+            add_offense(statement, message: format(DUPLICATE_MSG, handler:)) if seen.include?(handler)
+            seen << handler
+          end
+        end
+
+        private
+
+        def call_with_handlers?(node)
+          send = node.send_node
+          send.method_name == :call && send.receiver && node.arguments.empty?
+        end
+
+        def inside_operation?(node)
+          node.each_ancestor(:class).any? { |klass| operation_class?(klass) }
+        end
+
+        def block_statements(node)
+          return [] unless node.body
+
+          node.body.begin_type? ? node.body.children : [node.body]
+        end
+
+        def handler_name(statement)
+          send = statement.block_type? ? statement.send_node : statement
+          return unless send.send_type? && send.receiver.nil? && HANDLERS.include?(send.method_name)
+
+          send.method_name
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/def_outside_steps.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # Instance methods of an operation are steps, and steps live in `steps do ... end`. Base classes (no sections) are exempt.
+      #
+      #   # bad
+      #   def create_product; end
+      #
+      #   # good
+      #   steps do
+      #     def create_product; end
+      #   end
+      class DefOutsideSteps < Base
+        include OperationHelpers
+
+        MSG = 'Define `%<method>s` inside `steps do ... end`.'
+
+        def on_class(node)
+          return unless operation_class?(node) && !base_class?(node)
+
+          body_statements(node).each do |statement|
+            next unless statement.def_type?
+
+            add_offense(statement, message: format(MSG, method: statement.method_name))
+          end
+        end
+
+        private
+
+        # A class with no param, flow or steps is a base class (Subscriber, ApplicationOperation): helpers live there.
+        def base_class?(node)
+          sections(node).empty?
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/flow_required.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # An operation that declares params or steps must declare a `flow`. A class with none of the three is
+      # taken as a base class and left alone.
+      class FlowRequired < Base
+        include OperationHelpers
+
+        MSG = 'Operation has no `flow do ... end`.'
+
+        def on_class(node)
+          return unless operation_class?(node)
+
+          names = sections(node).map(&:first)
+          return if names.include?(:flow) || !names.intersect?(%i[param steps])
+
+          add_offense(node.identifier)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/missing_steps.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # In the editor only: marks `flow do` when the flow calls steps that `steps do ... end` does not define, so its
+      # code action creates all of them at once (each step's line, through UnknownStep, creates only its own). Off
+      # outside the editor's language server, so `rubocop -A` does not create the steps twice.
+      #
+      #   flow do             # Steps missing from steps do: create_order, notify
+      #     create_order
+      #     notify
+      #   end
+      class MissingSteps < Base
+        include OperationHelpers
+        extend AutoCorrector
+
+        MSG = 'Steps missing from `steps do ... end`: %<steps>s.'
+
+        def safe_autocorrect? = false
+
+        def on_class(node)
+          return unless RuboCop::LSP.enabled? && operation_class?(node)
+
+          steps_block = section(node, :steps)
+          flow_block = section(node, :flow)
+          return unless steps_block && flow_block&.block_type?
+
+          defined = step_names(steps_block)
+          flow_order = flow_step_names(flow_block)
+          missing = flow_order.reject { |name| defined.include?(name) }
+          return if missing.empty?
+
+          add_offense(flow_block.send_node, message: format(MSG, steps: missing.join(', '))) do |corrector|
+            add_steps(corrector, steps_block, flow_order, missing, missing)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/operation_helpers.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # Shared reading of an operation class body: which classes are operations, their sections
+      # (`param`, `flow`, `steps`, `returns`), the steps a flow calls and the methods `steps do` defines.
+      module OperationHelpers
+        # InternalOperation and ExternalOperation: the bases a chunk keeps in app/common.
+        OPERATION_PARENTS = %w[
+          Operation Operations::Base Operations::Internal Operations::External Operations::Subscriber ThunderOperation::Base
+          InternalOperation ExternalOperation
+        ].freeze
+        SECTIONS = %i[param flow steps returns].freeze
+        # Flow calls that are steps of the framework, not methods of the operation.
+        FLOW_KEYWORDS = %i[success render].freeze
+
+        def operation_class?(class_node)
+          parent = class_node.parent_class
+          return false unless parent&.const_type?
+
+          name = parent.const_name
+          OPERATION_PARENTS.any? { |suffix| name == suffix || name.end_with?("::#{suffix}") }
+        end
+
+        # Top-level statements of the class body.
+        def body_statements(class_node)
+          body = class_node.body
+          return [] unless body
+
+          body.begin_type? ? body.children : [body]
+        end
+
+        # [[section_name, node], ...] in source order; node is the send or the block wrapping it.
+        def sections(class_node)
+          body_statements(class_node).filter_map do |statement|
+            send = statement.block_type? ? statement.send_node : statement
+            next unless send.send_type? && send.receiver.nil? && SECTIONS.include?(send.method_name)
+
+            [send.method_name, statement]
+          end
+        end
+
+        def section(class_node, name)
+          sections(class_node).find { |section_name, _| section_name == name }&.last
+        end
+
+        # Names of the methods a `flow do ... end` block calls, including inside clauses.
+        def flow_step_names(flow_block)
+          return [] unless flow_block&.block_type? && flow_block.body
+
+          statements = flow_block.body.begin_type? ? flow_block.body.children : [flow_block.body]
+          statements.flat_map { |statement| flow_statement_names(statement) }.uniq
+        end
+
+        def flow_statement_names(statement)
+          if statement.block_type?
+            flow_step_names(statement)
+          elsif statement.send_type? && statement.receiver.nil? && !FLOW_KEYWORDS.include?(statement.method_name)
+            [statement.method_name]
+          else
+            []
+          end
+        end
+
+        # The `def` nodes directly inside `steps do ... end`.
+        def step_defs(steps_block)
+          return [] unless steps_block&.block_type? && steps_block.body
+
+          statements = steps_block.body.begin_type? ? steps_block.body.children : [steps_block.body]
+          statements.select(&:def_type?)
+        end
+
+        def step_names(steps_block)
+          step_defs(steps_block).map(&:method_name)
+        end
+
+        # WARN: AI MADE
+        # Writes an empty `def name` into `steps do`, in flow order (used by UnknownStep and MissingSteps).
+        # After the def of the closest earlier step that steps defines, else right after `steps do`. Corrections of one
+        # run (rubocop -A) that land on the same point keep the order they were added in, which is the flow order.
+        def add_steps(corrector, steps_block, flow_order, missing, names)
+          defs = step_defs(steps_block).to_h { |definition| [definition.method_name, definition] }
+          indent = ' ' * (steps_block.source_range.column + 2)
+
+          names.group_by { |name| anchor_for(name, flow_order, defs) }.each do |anchor, group|
+            methods = group.map { |name| "#{indent}def #{name}\n#{indent}end" }
+
+            text =
+              if anchor
+                methods.map { |method| "\n#{method}\n" }.join
+              elsif steps_block.body
+                methods.map { |method| "#{method}\n\n" }.join
+              else
+                first = missing.find { |other| anchor_for(other, flow_order, defs).nil? } == group.first
+                methods.each_with_index.map { |method, i| "#{"\n" unless first && i.zero?}#{method}\n" }.join
+              end
+
+            corrector.insert_after(line_start(anchor ? anchor.last_line + 1 : steps_block.loc.begin.line + 1), text)
+          end
+        end
+
+        # An empty range at column 0 of the line. Insertions go there because RuboCop's language server (1.90) turns
+        # a column into a position measuring the line of the offense, not the line of the edit: past the length of
+        # the offense line, the position comes back short (inside `do`). Column 0 is the same on any line.
+        def line_start(line)
+          buffer = processed_source.buffer
+          position = buffer.line_range(line).begin_pos
+          Parser::Source::Range.new(buffer, position, position)
+        end
+
+        # The def of the closest step the flow calls before this one and steps defines.
+        def anchor_for(name, flow_order, defs)
+          flow_order.take(flow_order.index(name)).reverse.filter_map { |earlier| defs[earlier] }.first
+        end
+
+        # Nodes that call `name` with no receiver inside `node`.
+        def bare_calls(node, name)
+          node.each_descendant(:send).select { |send| send.receiver.nil? && send.method_name == name }
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/operation_section_order.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # Sections of an operation come in a fixed order: `param`s, `flow`, `steps`, `returns`; each once (params many).
+      #
+      #   # bad
+      #   flow do ... end
+      #   param :name
+      #
+      #   # good
+      #   param :name
+      #   flow do ... end
+      #   steps do ... end
+      #   returns Models::Product
+      class OperationSectionOrder < Base
+        include OperationHelpers
+
+        ORDER_MSG = '`%<section>s` must come before `%<previous>s` (order: param, flow, steps, returns).'
+        DUPLICATE_MSG = '`%<section>s` is declared more than once.'
+
+        def on_class(node)
+          return unless operation_class?(node)
+
+          seen = []
+          sections(node).each do |name, statement|
+            check_order(name, statement, seen)
+            check_duplicate(name, statement, seen)
+            seen << name
+          end
+        end
+
+        private
+
+        def check_order(name, statement, seen)
+          later = seen.find { |previous| SECTIONS.index(previous) > SECTIONS.index(name) }
+          return unless later
+
+          add_offense(statement, message: format(ORDER_MSG, section: name, previous: later))
+        end
+
+        def check_duplicate(name, statement, seen)
+          return if name == :param || !seen.include?(name)
+
+          add_offense(statement, message: format(DUPLICATE_MSG, section: name))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/steps_cannot_call_steps.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # A step does not call another step; only the flow sequences them.
+      #
+      #   steps do
+      #     def create_product
+      #       charge_order          # bad
+      #     end
+      #   end
+      class StepsCannotCallSteps < Base
+        include OperationHelpers
+
+        MSG = 'Step `%<caller>s` must not call step `%<called>s`; only the flow calls steps.'
+
+        def on_class(node)
+          return unless operation_class?(node)
+
+          steps_block = section(node, :steps)
+          return unless steps_block
+
+          names = step_names(steps_block)
+          step_defs(steps_block).each do |definition|
+            names.each do |name|
+              bare_calls(definition, name).each do |call|
+                add_offense(call, message: format(MSG, caller: definition.method_name, called: name))
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/steps_order.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # Methods in `steps do ... end` are defined in the order the flow first calls them.
+      #
+      #   flow do
+      #     create_product
+      #     charge_order
+      #   end
+      #
+      #   steps do
+      #     def charge_order; end      # bad: the flow calls create_product first
+      #     def create_product; end
+      #   end
+      class StepsOrder < Base
+        include OperationHelpers
+
+        MSG = 'Step `%<step>s` is defined before `%<earlier>s`, but the flow calls it after.'
+
+        def on_class(node)
+          return unless operation_class?(node)
+
+          steps_block = section(node, :steps)
+          flow_block = section(node, :flow)
+          return unless steps_block && flow_block
+
+          check_order(flow_step_names(flow_block), step_defs(steps_block))
+        end
+
+        private
+
+        # Walks the defs the flow calls; a def whose flow position is lower than one already seen is out of place.
+        def check_order(flow_order, defs)
+          called = defs.select { |definition| flow_order.include?(definition.method_name) }
+          highest = nil
+
+          called.each do |definition|
+            position = flow_order.index(definition.method_name)
+
+            if highest && position < flow_order.index(highest.method_name)
+              add_offense(definition, message: format(MSG, step: highest.method_name, earlier: definition.method_name))
+            else
+              highest = definition
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/unknown_step.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # Every method the flow calls is defined inside `steps do ... end`. Checked only when that block exists.
+      #
+      #   flow do
+      #     change_order      # bad: steps defines charge_order
+      #   end
+      #
+      # The correction adds an empty `def` for each missing step, in the order the flow calls them: after the def of
+      # the step the flow calls before it, or first in `steps do` when none is defined. It is offered as a code action
+      # (quick fix) in the editor and applied by `rubocop -A`; being unsafe, format on save and `rubocop -a` skip it,
+      # so a step being typed in the flow does not grow an empty method by itself.
+      class UnknownStep < Base
+        include OperationHelpers
+        extend AutoCorrector
+
+        MSG = 'Step `%<step>s` is not defined in `steps do ... end`.'
+
+        def safe_autocorrect? = false
+
+        def on_class(node)
+          return unless operation_class?(node)
+
+          steps_block = section(node, :steps)
+          flow_block = section(node, :flow)
+          return unless steps_block && flow_block
+
+          defined = step_names(steps_block)
+          flow_order = flow_step_names(flow_block)
+          missing = flow_order.reject { |name| defined.include?(name) }
+          offered = []
+
+          flow_calls(flow_block).each do |call|
+            name = call.method_name
+            next if defined.include?(name)
+
+            add_offense(call, message: format(MSG, step: name)) do |corrector|
+              # Each line fixes its own step; a step called twice is added by its first call only.
+              next if offered.include?(name)
+
+              offered << name
+              add_steps(corrector, steps_block, flow_order, missing, [name])
+            end
+          end
+        end
+
+        private
+
+        def flow_calls(flow_block)
+          flow_block.each_descendant(:send).select do |send|
+            send.receiver.nil? && !send.block_literal? && !FLOW_KEYWORDS.include?(send.method_name) &&
+              flow_step_names(flow_block).include?(send.method_name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/thunderoperation/unused_step.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderOperation
+      # Every method defined inside `steps do ... end` is called by the flow.
+      class UnusedStep < Base
+        include OperationHelpers
+
+        MSG = 'Step `%<step>s` is not called by the flow.'
+
+        def on_class(node)
+          return unless operation_class?(node)
+
+          steps_block = section(node, :steps)
+          flow_block = section(node, :flow)
+          return unless steps_block && flow_block
+
+          called = flow_step_names(flow_block)
+          step_defs(steps_block).each do |definition|
+            next if called.include?(definition.method_name)
+
+            add_offense(definition, message: format(MSG, step: definition.method_name))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/thunderoperation/adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  class Adapter
+    attr_reader :operation_class
+
+    def initialize(operation_class)
+      @operation_class = operation_class
+    end
+
+    def execute(_params, _operation_instance, _options, &block)
+      block.call
+    end
+
+    class << self
+      attr_reader :adapted_block
+
+      def adapted(&block)
+        @adapted_block = block
+      end
+    end
+  end
+end

data/lib/thunderoperation/adapters/framer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Adapters
+    # WARN: AI MADE
+    # Renders the payload through `returns Hash do ... end` (or `Array do items Hash do ... end end`): each field is
+    # read from the object returned (a record, a Hash) and coerced to its type; a nested Hash or an association is
+    # read the same way, one item at a time for a list. The declaration becomes a ThunderFrame::Frame, built once.
+    class Framer < Adapter
+      # WARN: AI MADE
+      # A map (`keys Date`, `values Hash do ... end`): each value rendered through the values' frame, keys kept.
+      MapFrame = Data.define(:values_frame) do
+        def render_hash(entity)
+          return entity.map { |item| render_hash(item) } if entity.is_a?(Array)
+
+          entity&.transform_values { |value| values_frame ? values_frame.render_hash(value) : value }
+        end
+      end
+
+      def execute(_params, _operation_instance, _options, &block)
+        response = block.call
+        return response unless response.success? && operation_class.returns_frame
+
+        response.with(payload: operation_class.returns_frame.render_hash(response.payload))
+      end
+
+      # The frame of a Hash parameter; nil for a return that is not a Hash or a list of Hashes.
+      def self.frame_for(owner, parameter)
+        parameter = parameter.items if parameter.is_a?(Parameters::ArrayParameter)
+        return unless parameter.is_a?(Parameters::HashParameter)
+        return MapFrame.new(frame_for(owner, parameter.values)) if parameter.map?
+
+        ThunderFrame::Frame.new(:Result, owner:).tap { |frame| fill(frame, parameter) }
+      end
+
+      def self.fill(frame, parameter)
+        parameter.configuration.each do |name, child|
+          options = child.options.slice(:optional, :from, :as, :eager_loads)
+          nested = child.is_a?(Parameters::ArrayParameter) ? child.items : child
+
+          # A Hash with no fields declared, or a map, is a value: rendered as it comes.
+          if nested.is_a?(Parameters::HashParameter) && nested.configuration.any?
+            frame.association(name, **options) { Framer.fill(self, nested) }
+          elsif child.is_a?(Parameters::ArrayParameter)
+            raise Exceptions::DeclarationError, "#{frame.label}: #{name} is a list of values; a rendered return " \
+                                                'takes lists of Hashes only'
+          else
+            frame.field(name, child.type || String, **options)
+          end
+        end
+      end
+
+      adapted do
+        def self.renders_returns? = true
+
+        def self.returns_frame
+          return @returns_frame if defined?(@returns_frame)
+
+          @returns_frame = Framer.frame_for(self, returns)
+        end
+      end
+    end
+  end
+end

data/lib/thunderoperation/adapters/interruptable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ThunderOperation
+  module Adapters
+    class Interruptable < Adapter
+      def execute(_params, operation_instance, _options, &block)
+        block.call
+      rescue Exceptions::Interruption => e
+        operation_instance._failure(e)
+      end
+
+      adapted do
+        def interrupt
+          raise Exceptions::Interruption
+        end
+      end
+    end
+  end
+end