acts_as_calculator 0.1.0

data/lib/acts_as_calculator/cast_decimal.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  class CastDecimal
+    def self.call(value)
+      return value if value.is_a?(BigDecimal)
+
+      BigDecimal(value.to_s)
+    rescue ArgumentError, TypeError
+      raise Error, "cannot cast #{value.inspect} to a decimal"
+    end
+  end
+end

data/lib/acts_as_calculator/cast_json_safe.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  class CastJsonSafe
+    NATIVE = [NilClass, TrueClass, FalseClass, String, Integer, Float].freeze
+
+    def self.call(value)
+      case value
+      when Hash, Array then container(value)
+      # BigDecimal#to_json emits "0.1234e4"; a plain decimal string round-trips into the
+      # jsonb column as something a human (and a Phase 3 template) can read.
+      when BigDecimal then value.to_s("F")
+      when Symbol then value.to_s
+      when Rational then value.to_f
+      else scalar(value)
+      end
+    end
+
+    def self.container(value)
+      return value.map { |nested| call(nested) } if value.is_a?(Array)
+
+      value.to_h { |key, nested| [key.to_s, call(nested)] }
+    end
+    private_class_method :container
+
+    def self.scalar(value)
+      return value if NATIVE.any? { |type| value.is_a?(type) }
+      return value.iso8601 if value.respond_to?(:iso8601)
+      return call(value.to_h) if value.respond_to?(:to_h)
+
+      value.to_s
+    end
+    private_class_method :scalar
+  end
+end

data/lib/acts_as_calculator/cast_liquid_value.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "liquid"
+
+module ActsAsCalculator
+  # The one gate into a template's render context. Liquid only dispatches methods on
+  # `Liquid::Drop`s and hash-likes, so the sandbox holds exactly as long as nothing else
+  # is assigned — an allowlist here is what makes that a property of the code rather than
+  # a habit every caller has to remember.
+  class CastLiquidValue
+    PASS_THROUGH = [
+      ::NilClass, ::TrueClass, ::FalseClass, ::String, ::Integer, ::Float,
+      ::Date, ::Time, ::Liquid::Drop
+    ].freeze
+
+    def self.call(value)
+      case value
+      when ::Hash then value.to_h { |key, nested| [key.to_s, call(nested)] }
+      when ::Array then value.map { |nested| call(nested) }
+      when Result then ResultDrop.new(value)
+      else scalar(value)
+      end
+    end
+
+    def self.scalar(value)
+      return value if PASS_THROUGH.any? { |type| value.is_a?(type) }
+      return value.to_s if value.is_a?(::Symbol)
+      # BigDecimal#to_s emits engineering notation ("0.1e4"), which is not what belongs in
+      # rendered output; the plain-decimal form round-trips exactly back through CastDecimal.
+      return value.to_s("F") if value.is_a?(::BigDecimal)
+
+      time_like(value) || refuse(value)
+    end
+    private_class_method :scalar
+
+    # The one class a Rails host will hit that is neither a Date nor a Time, since
+    # `record.created_at` is the obvious thing to pass. Matched by name because the core
+    # layer must stay loadable without ActiveSupport, and named rather than duck-typed so
+    # this stays an allowlist — `respond_to?(:strftime)` would admit anything.
+    TIME_WITH_ZONE = "ActiveSupport::TimeWithZone"
+
+    # rubocop:disable Style/ClassEqualityComparison -- instance_of? would need the constant
+    def self.time_like(value)
+      value if value.class.name == TIME_WITH_ZONE
+    end
+    # rubocop:enable Style/ClassEqualityComparison
+    private_class_method :time_like
+
+    def self.refuse(value)
+      raise UnsafeAssignError,
+            "#{value.class} cannot be assigned into a template: wrap it in a Liquid::Drop " \
+            "that exposes only the methods a template may call, or pass a primitive"
+    end
+    private_class_method :refuse
+  end
+end

data/lib/acts_as_calculator/cast_variable_attributes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Both authoring paths hand over the same loose variable declaration — an import file's
+  # `variables` list and the API's — and both have to land on the same row, with the same
+  # defaults. Keeping the defaulting here is what stops the two from drifting.
+  class CastVariableAttributes
+    def self.call(variable)
+      variable = variable.to_h.transform_keys(&:to_s)
+
+      { name: variable["name"].to_s,
+        source_type: (variable["source_type"] || "context").to_s,
+        source_config: CastJsonSafe.(variable["source_config"] || {}),
+        required: variable.fetch("required", true) != false }
+    end
+  end
+end

data/lib/acts_as_calculator/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Host-facing settings, set from an initializer:
+  #
+  #   ActsAsCalculator.configure { |c| c.enable_api = true }
+  #
+  # `enable_api` is read per request by the routing constraint in `config/routes.rb`, not
+  # captured when the routes are drawn — so flipping it takes effect without a reload, and
+  # a host can gate the API on something it computes at boot.
+  class Configuration
+    attr_accessor :enable_api
+
+    def initialize
+      @enable_api = false
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  # Test-suite affordance: a host's own specs need to flip `enable_api` and put it back.
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/acts_as_calculator/distribute_remainder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  class DistributeRemainder
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(amount:, weights:, precision: Apportionment::DEFAULT_PRECISION)
+      @amount = amount
+      @weights = weights
+      @precision = precision
+    end
+
+    def call
+      shares = floors.dup
+      priority.first(leftover_units).each { |index| shares[index] += unit }
+      shares
+    end
+
+    private
+
+    attr_reader :amount, :weights, :precision
+
+    def unit
+      @unit ||= BigDecimal(1) / (10**precision)
+    end
+
+    def exact
+      @exact ||= DivideProportionally.(amount:, weights:)
+    end
+
+    def floors
+      @floors ||= exact.map { |share| (share / unit).floor * unit }
+    end
+
+    def leftover_units
+      ((amount - floors.sum) / unit).round
+    end
+
+    def priority
+      remainders = exact.zip(floors).map { |share, floor| share - floor }
+
+      (0...weights.size).sort_by { |index| [-remainders[index], index] }
+    end
+  end
+end

data/lib/acts_as_calculator/divide_proportionally.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  class DivideProportionally
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(amount:, weights:)
+      @amount = amount
+      @weights = weights
+    end
+
+    def call
+      total = weights.sum
+      raise ApportionmentError, "cannot apportion across zero total weight" if total.zero?
+
+      weights.map { |weight| amount * weight / total }
+    end
+
+    private
+
+    attr_reader :amount, :weights
+  end
+end

data/lib/acts_as_calculator/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Rails::Engine::Configuration reaches for ActionDispatch::Routing::RouteSet the moment
+# isolate_namespace touches `config`, and railties depends on actionpack anyway, so this
+# is a load-order fix rather than an extra dependency.
+require "action_dispatch"
+require "rails"
+require "rails/engine"
+require "active_record"
+
+module ActsAsCalculator
+  class Engine < ::Rails::Engine
+    isolate_namespace ActsAsCalculator
+
+    config.generators do |generators|
+      generators.test_framework :rspec
+    end
+  end
+end

data/lib/acts_as_calculator/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class Error < StandardError; end
+
+  class EvaluationError < Error; end
+  class MissingVariableError < Error; end
+  class VariableResolutionError < Error; end
+  class UnknownSourceTypeError < Error; end
+  class MissingLookupTableError < Error; end
+  class TierNotFoundError < Error; end
+  class UnknownStrategyError < Error; end
+  class ApportionmentError < Error; end
+  class AggregationError < Error; end
+  class FormulaNotFoundError < Error; end
+  class NoEffectiveVersionError < Error; end
+  class TemplateNotFoundError < Error; end
+  class TemplateRenderError < Error; end
+  class UnsafeAssignError < Error; end
+  class PartialSupersedeError < Error; end
+  class ImportError < Error; end
+  class LookupTableInUseError < ImportError; end
+end

data/lib/acts_as_calculator/evaluate_expression.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "dentaku"
+
+module ActsAsCalculator
+  class EvaluateExpression
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(expression:, inputs: {}, calculator: nil, formula_version: nil, as_of: nil)
+      @expression = expression
+      @inputs = inputs
+      @calculator = calculator
+      @formula_version = formula_version
+      @as_of = as_of
+    end
+
+    def call
+      value = evaluate
+
+      Result.new(value:, breakdown: breakdown_for(value), formula_version:, as_of:)
+    end
+
+    private
+
+    attr_reader :expression, :inputs, :formula_version, :as_of
+
+    # Dentaku evaluates an expression as one unit, so the trace is the resolved inputs
+    # and the final value; a step-by-step breakdown needs formulas decomposed into named
+    # sub-expressions, which is deliberately deferred (docs/PLAN.md, "Open risks").
+    def breakdown_for(value)
+      { expression:, inputs:, value: }
+    end
+
+    def evaluate
+      calculator.evaluate!(expression, inputs)
+    rescue Dentaku::UnboundVariableError => e
+      raise MissingVariableError,
+            "#{expression.inspect} references unresolved variables: #{e.unbound_variables.join(", ")}"
+    rescue Dentaku::Error, ::ZeroDivisionError => e
+      raise EvaluationError, "could not evaluate #{expression.inspect}: #{e.message}"
+    end
+
+    def calculator
+      @calculator ||= BuildCalculator.()
+    end
+  end
+end

data/lib/acts_as_calculator/evaluate_formula.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class EvaluateFormula
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(calculable:, key:, scope: nil, owner: nil, as_of: nil,
+                   context: {}, dry_run: false, calculators: CalculatorCache.default)
+      @calculable = calculable
+      @key = key
+      @scope = scope
+      @owner = owner
+      @as_of = CastDate.(as_of || Date.current)
+      @context = context
+      @dry_run = dry_run
+      @calculators = calculators
+    end
+
+    def call
+      version = ResolveFormulaVersion.(key:, scope:, owner:, as_of:)
+      inputs = resolve_variables(version)
+      result = evaluate(version, inputs)
+
+      PersistRun.(calculable:, formula_version: version, as_of:, result:) unless dry_run
+      result
+    end
+
+    private
+
+    attr_reader :calculable, :key, :scope, :owner, :as_of, :context, :dry_run, :calculators
+
+    def resolve_variables(version)
+      ResolveVariables.(
+        specs: version.variables.to_a,
+        calculable:,
+        context:,
+        lookups: BuildLookups.(formula_version: version, owner:)
+      )
+    end
+
+    def evaluate(version, inputs)
+      EvaluateExpression.(
+        expression: version.expression,
+        inputs:,
+        calculator: calculators.fetch(version.id),
+        formula_version: version,
+        as_of:
+      )
+    end
+  end
+end

data/lib/acts_as_calculator/find_lookup_table_references.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Which formula versions would resolve to *this* lookup table if they ran now.
+  #
+  # A variable names a table by key, never by id, and `BuildLookups` turns that key into a
+  # row through `FindOwnedRecord` — owner first, global second. So "does version X use
+  # table Y" cannot be answered by a foreign key or by matching keys alone: a global table
+  # is used by an owned formula only when that owner has no table of its own with the same
+  # key. Re-running the very same resolution is what keeps this answer from drifting away
+  # from what an actual calculation would do.
+  class FindLookupTableReferences
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(lookup_table:, statuses: nil)
+      @lookup_table = lookup_table
+      @statuses = statuses
+    end
+
+    def call
+      candidates.select { |variable| resolves_here?(variable.formula_version.formula) }
+                .map(&:formula_version)
+                .uniq
+    end
+
+    private
+
+    attr_reader :lookup_table, :statuses
+
+    def candidates
+      by_key(scoped_variables.includes(formula_version: :formula))
+    end
+
+    def scoped_variables
+      variables = Variable.where(source_type: "lookup")
+                          .joins(formula_version: :formula)
+                          .where(Formula.table_name => { scope: lookup_table.scope })
+      statuses.nil? ? variables : variables.where(FormulaVersion.table_name => { status: statuses })
+    end
+
+    # `lookup_table_key` reads source_config, whose shape is JSON — portable across the
+    # adapters this gem supports only in Ruby.
+    def by_key(variables)
+      variables.select { |variable| variable.lookup_table_key == lookup_table.key }
+    end
+
+    def resolves_here?(formula)
+      candidate_owners(formula).any? do |owner|
+        FindOwnedRecord.(relation: LookupTable.all, key: lookup_table.key,
+                         scope: formula.scope, owner:) == lookup_table
+      end
+    end
+
+    # Which owner a version's tables resolve under is the *caller's* owner, not the formula's:
+    # `Calculable#calculate` forwards `owner:` through `EvaluateFormula` to `BuildLookups`. An
+    # owned formula can only ever have been reached by its own owner, so that is the one
+    # candidate. A global formula is reached by every owner — but it can only land on *this*
+    # row as the global table (owner nil) or as this row's owner shadowing it, so those two
+    # are the whole candidate set, and checking more would pin tables nothing can reach.
+    def candidate_owners(formula)
+      return [formula.owner] if formula.owner
+
+      [nil, lookup_table.owner].uniq
+    end
+  end
+end

data/lib/acts_as_calculator/find_owned_record.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class FindOwnedRecord
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(relation:, key:, scope: nil, owner: nil)
+      @relation = relation
+      @key = key.to_s
+      @scope = (scope || DEFAULT_SCOPE).to_s
+      @owner = owner
+    end
+
+    def call
+      owned || global
+    end
+
+    private
+
+    attr_reader :relation, :key, :scope, :owner
+
+    def owned
+      return nil if owner.nil?
+
+      candidates.owned_by(owner).first
+    end
+
+    def global
+      candidates.global.first
+    end
+
+    def candidates
+      relation.where(key:, scope:)
+    end
+  end
+end

data/lib/acts_as_calculator/find_tier.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class FindTier
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(tiers:, amount:)
+      @tiers = tiers
+      @amount = amount
+    end
+
+    def call
+      built = tiers.map { |tier| Tier.build(tier) }
+
+      built.find { |tier| tier.covers?(amount) } ||
+        raise(TierNotFoundError, "no tier covers #{amount.inspect} in #{built.inspect}")
+    end
+
+    private
+
+    attr_reader :tiers, :amount
+  end
+end

data/lib/acts_as_calculator/formula_version_drop.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module ActsAsCalculator
+  # Liquid::Drop only invokes public methods declared on the subclass itself — everything
+  # Object and Liquid::Drop already answer to is blacklisted — so this list *is* the set of
+  # things a template can reach on a formula version.
+  class FormulaVersionDrop < Liquid::Drop
+    def initialize(formula_version)
+      super()
+      @formula_version = formula_version
+    end
+
+    def key
+      formula_version.formula.key
+    end
+
+    def scope
+      formula_version.formula.scope
+    end
+
+    def version_number
+      formula_version.version_number
+    end
+
+    def expression
+      formula_version.expression
+    end
+
+    def status
+      formula_version.status
+    end
+
+    def effective_from
+      formula_version.effective_from
+    end
+
+    def effective_to
+      formula_version.effective_to
+    end
+
+    def change_note
+      formula_version.change_note
+    end
+
+    def to_s
+      key.to_s
+    end
+
+    private
+
+    attr_reader :formula_version
+  end
+end

data/lib/acts_as_calculator/function_registry.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  class FunctionRegistry
+    Definition = Data.define(:name, :type, :implementation)
+
+    BRACKET = lambda { |amount, tiers|
+      FindTier.(tiers:, amount:).value
+    }
+
+    PROGRESSIVE_BRACKET = lambda { |amount, tiers|
+      total = CastDecimal.(amount)
+
+      tiers.map { |tier| Tier.build(tier) }.sum(BigDecimal(0)) do |tier|
+        floor = CastDecimal.(tier.from || 0)
+        ceiling = tier.to.nil? ? total : [total, CastDecimal.(tier.to)].min
+        band = ceiling - floor
+
+        band.positive? ? band * CastDecimal.(tier.value) : BigDecimal(0)
+      end
+    }
+
+    ROUND_CURRENCY = lambda { |amount, precision = 2|
+      CastDecimal.(amount).round(Integer(precision), :half_up)
+    }
+
+    PRORATE = lambda { |amount, part, whole|
+      divisor = CastDecimal.(whole)
+      raise EvaluationError, "cannot prorate over a whole of zero" if divisor.zero?
+
+      CastDecimal.(amount) * CastDecimal.(part) / divisor
+    }
+
+    BUILTINS = {
+      bracket: BRACKET,
+      progressive_bracket: PROGRESSIVE_BRACKET,
+      round_currency: ROUND_CURRENCY,
+      prorate: PRORATE
+    }.freeze
+
+    def self.default
+      @default ||= new
+    end
+
+    def initialize
+      @definitions = {}
+      BUILTINS.each { |name, implementation| register(name:, implementation:) }
+    end
+
+    def register(name:, implementation:, type: :numeric)
+      # Dentaku derives a function's arity from its implementation's #parameters, and a
+      # non-lambda proc reports every parameter as optional, so arity checking silently
+      # stops working for anything registered as a bare block or proc.
+      raise ArgumentError, "implementation for #{name.inspect} must be a lambda" unless implementation.lambda?
+
+      definitions[key_for(name)] = Definition.new(name: key_for(name), type:, implementation:)
+      self
+    end
+
+    def registered?(name)
+      definitions.key?(key_for(name))
+    end
+
+    def to_a
+      definitions.values
+    end
+
+    def install(calculator)
+      to_a.each { |it| calculator.add_function(it.name, it.type, it.implementation) }
+      calculator
+    end
+
+    private
+
+    attr_reader :definitions
+
+    def key_for(name)
+      name.to_s.downcase
+    end
+  end
+end