Allow optional passing of options to calculators

For the upcoming "strikethrough prices"/"promotion previews" feature, we
need to allow passing options to calculator's `compute` methods.

For strikethrough prices, we will need the current order and the desired
quantity to be passed into the calculator, and this commit allows
passing any desired options.

Since calculators are polymorphic in all directions and can be used in
all kinds of context, we don't specify which options are possible.

This also does the groundwork for allowing the
SolidusPromotions::Benefit to take options and pass them on to its
calculator.

Because these methods are used a lot in Solidus, adds YARD-style
documentation to the modified methods.

Author: mamhoff

core/app/models/spree/calculator.rb

@@ -6,16 +6,41 @@ class Calculator < Spree::Base
 
     belongs_to :calculable, polymorphic: true, optional: true
 
-    # This method calls a compute_<computable> method. must be overriden in concrete calculator.
+    # Computes an amount based on the calculable and the computable parameter.
     #
-    # It should return amount computed based on #calculable and the computable parameter
-    def compute(computable)
+    # This method dynamically calls a compute_<computable> method based on the class
+    # of the computable parameter. Concrete calculator classes must implement the
+    # appropriate compute method for each computable type they support.
+    #
+    # For example, if the computable is a Spree::LineItem, this will call
+    # compute_line_item(computable, ...). If the computable is a Spree::Order,
+    # it will call compute_order(computable, ...).
+    #
+    # @param computable [Object] The object to compute the amount for (e.g.,
+    #                            Spree::LineItem, Spree::Order, Spree::Shipment,
+    #                            Spree::ShippingRate)
+    # @param ... [args, kwargs] Additional arguments passed to the specific compute method
+    #
+    # @return [BigDecimal, Numeric] The computed amount
+    #
+    # @raise [NotImplementedError] If the calculator doesn't implement the required compute method
+    #
+    # @example Implementing a calculator for line items
+    #   class MyCalculator < Spree::Calculator
+    #     def compute_line_item(line_item)
+    #       line_item.amount * 0.1 # 10% of line item amount
+    #     end
+    #   end
+    #
+    # @see Spree::CalculatedAdjustments for how calculators connect to calculables, such as
+    #      Spree::TaxRate, Spree::ShippingRate, SolidusPromotions::Benefit, or Spree::PromotionAction
+    def compute(computable, ...)
       # Spree::LineItem -> :compute_line_item
       computable_name = computable.class.name.demodulize.underscore
-      method_name = "compute_#{computable_name}".to_sym
+      method_name = :"compute_#{computable_name}"
       calculator_class = self.class
       if respond_to?(method_name)
-        send(method_name, computable)
+        send(method_name, computable, ...)
       else
         raise NotImplementedError, "Please implement '#{method_name}(#{computable_name})' in your calculator: #{calculator_class.name}"
       end

core/spec/models/spree/calculator_spec.rb

@@ -9,7 +9,7 @@ def self.name
         "SimpleCalculator"
       end
 
-      def compute_simple_computable(_)
+      def compute_simple_computable(_, _options = {})
         "computed"
       end
     end
@@ -53,5 +53,15 @@ def self.name
         expect { subject }.to raise_error NotImplementedError, /Please implement \'compute_line_item\(line_item\)\' in your calculator/
       end
     end
+
+    context "with options" do
+      let(:order) { double(Spree::Order) }
+      subject { calculator.compute(computable, order: order) }
+
+      it "passes the options to compute_simple_computable" do
+        expect(calculator).to receive(:compute_simple_computable).with(computable, order: order)
+        subject
+      end
+    end
   end
 end

promotions/app/models/solidus_promotions/benefit.rb

@@ -29,8 +29,25 @@ def can_discount?(object)
         "`SolidusPromotions::Benefits::LineItemBenefit` or `SolidusPromotions::Benefits::ShipmentBenefit` modules"
     end
 
-    def discount(adjustable)
-      amount = compute_amount(adjustable)
+    # Calculates and returns a discount for the given adjustable object.
+    #
+    # This method computes the discount amount using the benefit's calculator and returns
+    # an ItemDiscount object representing the discount to be applied. If the computed
+    # amount is zero, no discount is returned.
+    #
+    # @param adjustable [Object] The object to calculate the discount for (e.g., LineItem, Order, Shipment)
+    # @param ... [args, kwargs] Additional arguments passed to the calculator's compute method
+    #
+    # @return [SolidusPromotions::ItemDiscount, nil] An ItemDiscount object if a discount applies, nil if the amount is zero
+    #
+    # @example Calculating a discount for a line item
+    #   benefit.discount(line_item)
+    #   # => #<SolidusPromotions::ItemDiscount item: #<Spree::LineItem>, amount: -10.00, ...>
+    #
+    # @see #compute_amount
+    # @see #adjustment_label
+    def discount(adjustable, ...)
+      amount = compute_amount(adjustable, ...)
       return if amount.zero?
       ItemDiscount.new(
         item: adjustable,
@@ -41,8 +58,8 @@ def discount(adjustable)
     end
 
     # Ensure a negative amount which does not exceed the object's amount
-    def compute_amount(adjustable)
-      promotion_amount = calculator.compute(adjustable) || Spree::ZERO
+    def compute_amount(adjustable, ...)
+      promotion_amount = calculator.compute(adjustable, ...) || Spree::ZERO
       [adjustable.discountable_amount, promotion_amount.abs].min * -1
     end
 

promotions/spec/models/solidus_promotions/benefit_spec.rb

@@ -104,6 +104,22 @@
         expect(subject).to be nil
       end
     end
+
+    context "if passing in extra options" do
+      let(:calculator_class) do
+        Class.new(Spree::Calculator) do
+          def compute_line_item(_line_item, _options) = 1
+        end
+      end
+      let(:calculator) { calculator_class.new }
+      let(:discountable) { build(:line_item) }
+
+      subject { benefit.discount(discountable, extra_data: "foo") }
+      it "passes the option on to the calculator" do
+        expect(calculator).to receive(:compute_line_item).with(discountable, extra_data: "foo").and_return(1)
+        subject
+      end
+    end
   end
 
   describe ".original_promotion_action" do