acts_as_calculator 0.1.0

data/app/models/acts_as_calculator/formula_version.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class FormulaVersion < Record
+    self.table_name = "calculator_formula_versions"
+
+    DRAFT = "draft"
+    ACTIVE = "active"
+    RETIRED = "retired"
+    STATUSES = [DRAFT, ACTIVE, RETIRED].freeze
+
+    # `effective_to` and `status` stay writable so an active version can be closed out or
+    # retired; rewriting what was in force on a date already calculated is what's banned.
+    IMMUTABLE_ONCE_ACTIVE = %w[formula_id version_number expression effective_from].freeze
+
+    belongs_to :formula, inverse_of: :versions
+
+    has_many :variables,
+             class_name: "ActsAsCalculator::Variable",
+             foreign_key: :formula_version_id,
+             inverse_of: :formula_version,
+             dependent: :destroy
+
+    has_many :runs,
+             class_name: "ActsAsCalculator::Run",
+             foreign_key: :formula_version_id,
+             inverse_of: :formula_version,
+             dependent: :restrict_with_error
+
+    validates :expression, presence: true
+    validates :effective_from, presence: true
+    validates :status, inclusion: { in: STATUSES }
+    validates :version_number,
+              presence: true,
+              numericality: { only_integer: true, greater_than: 0 },
+              uniqueness: { scope: :formula_id }
+
+    validate :effective_range_ordered
+    validate :no_overlapping_active_version
+    validate :active_content_unchanged, on: :update
+
+    scope :active, -> { where(status: ACTIVE) }
+    scope :open_ended_or_ending_on_or_after, lambda { |date|
+      where("#{quoted_table_name}.effective_to IS NULL OR #{quoted_table_name}.effective_to >= :date", date:)
+    }
+    scope :covering, ->(date) { where(effective_from: ..date).open_ended_or_ending_on_or_after(date) }
+
+    def active?
+      status == ACTIVE
+    end
+
+    def covers?(date)
+      return false if effective_from.nil? || effective_from > date
+
+      effective_to.nil? || effective_to >= date
+    end
+
+    private
+
+    def effective_range_ordered
+      return if effective_from.nil? || effective_to.nil? || effective_to >= effective_from
+
+      errors.add(:effective_to, "must be on or after effective_from")
+    end
+
+    def no_overlapping_active_version
+      return unless active?
+      return if formula_id.nil? || effective_from.nil?
+
+      errors.add(:effective_from, "overlaps an active version of this formula") if overlapping_siblings.exists?
+    end
+
+    def overlapping_siblings
+      siblings = self.class.active.where(formula_id:)
+      siblings = siblings.where.not(id:) if id
+      siblings = siblings.where(effective_from: ..effective_to) if effective_to
+      siblings.open_ended_or_ending_on_or_after(effective_from)
+    end
+
+    def active_content_unchanged
+      return unless status_was == ACTIVE
+
+      (changed & IMMUTABLE_ONCE_ACTIVE).each do |attribute|
+        errors.add(attribute, "cannot be changed on an active version — create a new version instead")
+      end
+    end
+  end
+end

data/app/models/acts_as_calculator/lookup_table.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class LookupTable < Record
+    self.table_name = "calculator_lookup_tables"
+
+    belongs_to :owner, polymorphic: true, optional: true
+
+    has_many :entries,
+             class_name: "ActsAsCalculator::LookupTableEntry",
+             foreign_key: :lookup_table_id,
+             inverse_of: :lookup_table,
+             dependent: :destroy
+
+    validates :key, presence: true, uniqueness: { scope: %i[scope owner_type owner_id] }
+    validates :scope, presence: true
+
+    scope :owned_by, ->(owner) { where(owner_type: owner&.class&.polymorphic_name, owner_id: owner&.id) }
+    scope :global, -> { where(owner_type: nil, owner_id: nil) }
+
+    def tiers
+      entries.ordered.map { |entry| Tier.new(from: entry.from, to: entry.to, value: entry.value) }
+    end
+  end
+end

data/app/models/acts_as_calculator/lookup_table_entry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class LookupTableEntry < Record
+    self.table_name = "calculator_lookup_table_entries"
+
+    belongs_to :lookup_table, inverse_of: :entries
+
+    validates :value, presence: true
+    validates :position, presence: true, numericality: { only_integer: true }
+    validate :bounds_ordered
+
+    # `from`/`to` are half-open and nullable on both ends, so neither is orderable in SQL
+    # in a way that puts an unbounded floor first across every adapter — position is the
+    # explicit, adapter-independent answer.
+    scope :ordered, -> { order(:position, :id) }
+
+    private
+
+    def bounds_ordered
+      return if from.nil? || to.nil? || to > from
+
+      errors.add(:to, "must be greater than from")
+    end
+  end
+end

data/app/models/acts_as_calculator/record.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class Record < ::ActiveRecord::Base
+    self.abstract_class = true
+
+    # Set here rather than inherited from the host: `belongs_to_required_by_default` only
+    # becomes true via `config.load_defaults`, and whether a run may be saved without the
+    # formula version it applied is not the host's decision to make.
+    self.belongs_to_required_by_default = true
+  end
+end

data/app/models/acts_as_calculator/run.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class Run < Record
+    self.table_name = "calculator_runs"
+
+    belongs_to :calculable, polymorphic: true
+    belongs_to :formula_version, inverse_of: :runs
+
+    validates :as_of_date, presence: true
+    validates :result, presence: true
+
+    scope :recent_first, -> { order(as_of_date: :desc, id: :desc) }
+    scope :for_formula_key, lambda { |key|
+      joins(formula_version: :formula).where(calculator_formulas: { key: key.to_s })
+    }
+
+    # The audit trail is append-only: a correction is a new run, never an edit of the row
+    # that recorded what was actually applied.
+    def readonly?
+      persisted?
+    end
+  end
+end

data/app/models/acts_as_calculator/template.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class Template < Record
+    self.table_name = "calculator_templates"
+
+    HTML = "html"
+    TEXT = "text"
+    FORMATS = [HTML, TEXT].freeze
+
+    belongs_to :owner, polymorphic: true, optional: true
+
+    validates :key, presence: true, uniqueness: { scope: %i[scope owner_type owner_id version_number] }
+    validates :scope, presence: true
+    validates :body, presence: true
+    validates :format, inclusion: { in: FORMATS }
+    validates :version_number, presence: true, numericality: { only_integer: true, greater_than: 0 }
+
+    # Only on update: a create demotes its siblings in before_create, which runs *after*
+    # validation, so running this on create would flag the version it is about to replace.
+    validate :single_current_version, on: :update
+
+    before_create :demote_other_versions, if: :current?
+
+    scope :owned_by, ->(owner) { where(owner_type: owner&.class&.polymorphic_name, owner_id: owner&.id) }
+    scope :global, -> { where(owner_type: nil, owner_id: nil) }
+    scope :latest_first, -> { order(version_number: :desc, id: :desc) }
+    scope :current, -> { where(current: true) }
+    scope :version_siblings_of, lambda { |template|
+      where(key: template.key, scope: template.scope,
+            owner_type: template.owner_type, owner_id: template.owner_id)
+    }
+
+    def next_version_number
+      (self.class.version_siblings_of(self).maximum(:version_number) || 0) + 1
+    end
+
+    private
+
+    def other_versions
+      siblings = self.class.version_siblings_of(self)
+      persisted? ? siblings.where.not(id:) : siblings
+    end
+
+    def demote_other_versions
+      other_versions.current.update_all(current: false, updated_at: Time.current)
+    end
+
+    def single_current_version
+      return unless current?
+      return unless other_versions.current.exists?
+
+      errors.add(:current, "another version of this template is already current — use PromoteTemplate")
+    end
+  end
+end

data/app/models/acts_as_calculator/variable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class Variable < Record
+    self.table_name = "calculator_variables"
+
+    SOURCE_TYPES = ResolveVariables::SOURCE_TYPES.map(&:to_s).freeze
+
+    belongs_to :formula_version, inverse_of: :variables
+
+    validates :name, presence: true, uniqueness: { scope: :formula_version_id }
+    validates :source_type, inclusion: { in: SOURCE_TYPES }
+
+    def lookup_table_key
+      return nil unless source_type == "lookup"
+
+      (source_config || {}).fetch("table", name).to_s
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# The API ships off (docs/PLAN.md, "Authoring paths"): a host opts in with
+# `ActsAsCalculator.configure { |c| c.enable_api = true }`.
+#
+# The gate is a routing constraint rather than a `before_action` on purpose. A controller
+# guard leaves the route registered — the router matches it, instantiates the controller,
+# and the controller declines — which means the endpoints exist, answer HEAD/OPTIONS, show
+# up in `rails routes`, and are one forgotten `skip_before_action` away from being live.
+# A constraint that returns false makes the route not match at all: the engine's router
+# passes, the host's router finds nothing, and the request 404s because there is no such
+# path. Off means absent, not refused.
+#
+# The lambda is evaluated per request, so the flag is read at match time, not captured when
+# the routes were drawn.
+ActsAsCalculator::Engine.routes.draw do
+  constraints(->(_request) { ActsAsCalculator.configuration.enable_api }) do
+    resources :formulas, only: %i[index show create update destroy] do
+      resources :versions, only: %i[index show create], controller: "formula_versions"
+    end
+
+    # No `update`: a template body is versioned for rollback, so a change publishes a new
+    # version (POST) and going back promotes an old one — editing a row in place would
+    # rewrite the history that makes rollback possible.
+    resources :templates, only: %i[index show create destroy] do
+      member do
+        post :preview
+        post :promote
+      end
+    end
+
+    # docs/PLAN.md's JSON import, reachable over HTTP — the same ImportDefinitions the
+    # generator and the rake task call, handed a parsed body instead of a file.
+    post "import", to: "imports#create"
+  end
+end

data/lib/acts_as_calculator/aggregate_results.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  class AggregateResults
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(records:, formula:, as_of: nil, group_by: nil)
+      @records = records
+      @formula = formula
+      @as_of = as_of
+      @group_by = group_by
+    end
+
+    def call
+      return total(rows) if group_by.nil?
+
+      rows.group_by { |record| group_key(record) }.transform_values { |group| total(group) }
+    end
+
+    private
+
+    attr_reader :records, :formula, :as_of, :group_by
+
+    def rows
+      @rows ||= records.to_a
+    end
+
+    def total(group)
+      group.sum(BigDecimal(0)) { |record| CastDecimal.(value_of(record)) }
+    end
+
+    def value_of(record)
+      outcome = calculate(record)
+      return outcome.value if outcome.respond_to?(:value)
+      return outcome if outcome.is_a?(Numeric)
+
+      raise AggregationError, "expected a Result or Numeric from #{record.inspect}, got #{outcome.inspect}"
+    end
+
+    def calculate(record)
+      return formula.call(record) if formula.respond_to?(:call)
+      raise AggregationError, "#{record.class} does not respond to #calculate" unless record.respond_to?(:calculate)
+
+      as_of.nil? ? record.calculate(formula) : record.calculate(formula, as_of:)
+    end
+
+    def group_key(record)
+      return group_by.call(record) if group_by.respond_to?(:call)
+
+      record.public_send(group_by)
+    end
+  end
+end

data/lib/acts_as_calculator/aggregation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  module Aggregation
+    def self.sum(records, formula:, as_of: nil, group_by: nil)
+      AggregateResults.(records:, formula:, as_of:, group_by:)
+    end
+  end
+end

data/lib/acts_as_calculator/apportion_amount.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  class ApportionAmount
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(amount:, among:, by: nil, strategy: :proportional,
+                   precision: Apportionment::DEFAULT_PRECISION)
+      @amount = amount
+      @among = among
+      @by = by
+      @strategy = strategy
+      @precision = precision
+    end
+
+    def call
+      raise ApportionmentError, "cannot apportion among an empty collection" if members.empty?
+
+      shares = Apportionment.strategy(strategy).call(amount: total, weights:, precision:)
+
+      members.zip(weights, shares).map do |member, weight, share|
+        Apportionment::Share.new(member:, weight:, amount: share)
+      end
+    end
+
+    private
+
+    attr_reader :amount, :among, :by, :strategy, :precision
+
+    def total
+      @total ||= CastDecimal.(amount)
+    end
+
+    def members
+      @members ||= among.to_a
+    end
+
+    def weights
+      @weights ||= members.map { |member| weight_for(member) }
+    end
+
+    def weight_for(member)
+      return BigDecimal(1) if by.nil? || strategy.to_sym == :equal
+
+      weight = CastDecimal.(raw_weight(member))
+      raise ApportionmentError, "negative weight #{weight.to_f} from #{by.inspect}" if weight.negative?
+
+      weight
+    end
+
+    def raw_weight(member)
+      value = by.respond_to?(:call) ? by.call(member) : member.public_send(by)
+      raise ApportionmentError, "#{by.inspect} returned nil for #{member.inspect}" if value.nil?
+
+      value
+    end
+  end
+end

data/lib/acts_as_calculator/apportionment.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module ActsAsCalculator
+  module Apportionment
+    Share = Data.define(:member, :weight, :amount)
+
+    DEFAULT_PRECISION = 2
+
+    PROPORTIONAL = lambda { |amount:, weights:, **|
+      DivideProportionally.(amount:, weights:)
+    }
+
+    EQUAL = lambda { |amount:, weights:, **|
+      Array.new(weights.size) { amount / weights.size }
+    }
+
+    LARGEST_REMAINDER = lambda { |amount:, weights:, precision:|
+      DistributeRemainder.(amount:, weights:, precision:)
+    }
+
+    def self.split(amount:, among:, by: nil, strategy: :proportional, precision: DEFAULT_PRECISION)
+      ApportionAmount.(amount:, among:, by:, strategy:, precision:)
+    end
+
+    def self.register_strategy(name, strategy)
+      registry[name.to_sym] = strategy
+      self
+    end
+
+    def self.unregister_strategy(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    def self.strategy(name)
+      registry.fetch(name.to_sym) do
+        raise UnknownStrategyError,
+              "unknown apportionment strategy #{name.inspect} (known: #{known_strategies.join(", ")})"
+      end
+    end
+
+    def self.known_strategies
+      registry.keys
+    end
+
+    def self.registry
+      @registry ||= {}
+    end
+    private_class_method :registry
+
+    register_strategy(:proportional, PROPORTIONAL)
+    register_strategy(:equal, EQUAL)
+    register_strategy(:largest_remainder, LARGEST_REMAINDER)
+  end
+end

data/lib/acts_as_calculator/build_calculator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "dentaku"
+
+module ActsAsCalculator
+  class BuildCalculator
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(functions: FunctionRegistry.default, case_sensitive: false)
+      @functions = functions
+      @case_sensitive = case_sensitive
+    end
+
+    def call
+      functions.install(Dentaku::Calculator.new(case_sensitive:))
+    end
+
+    private
+
+    attr_reader :functions, :case_sensitive
+  end
+end

data/lib/acts_as_calculator/build_lookups.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class BuildLookups
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(formula_version:, owner: nil)
+      @formula_version = formula_version
+      @owner = owner
+    end
+
+    def call
+      table_keys.to_h { |key| [key, tiers_for(key)] }
+    end
+
+    private
+
+    attr_reader :formula_version, :owner
+
+    def table_keys
+      formula_version.variables.filter_map(&:lookup_table_key).uniq
+    end
+
+    def tiers_for(key)
+      table = FindOwnedRecord.(relation: LookupTable.all, key:, scope: formula.scope, owner: owner || formula.owner)
+      raise MissingLookupTableError, "no lookup table #{key.inspect} in scope #{formula.scope.inspect}" if table.nil?
+
+      table.tiers
+    end
+
+    def formula
+      @formula ||= formula_version.formula
+    end
+  end
+end

data/lib/acts_as_calculator/calculable.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module ActsAsCalculator
+  module Calculable
+    extend ::ActiveSupport::Concern
+
+    included do
+      # No `dependent:` on purpose. Whether an audit trail outlives the record it audited
+      # is the host app's retention policy, and Run#readonly? makes `:destroy` raise.
+      has_many :calculator_runs,
+               class_name: "ActsAsCalculator::Run",
+               as: :calculable,
+               inverse_of: :calculable
+
+      class_attribute :calculator_scope_name, instance_writer: false, default: DEFAULT_SCOPE
+    end
+
+    class_methods do
+      def calculator_scope(name)
+        self.calculator_scope_name = name.to_s
+      end
+    end
+
+    # Leftover keywords splat into the calculation context, which makes `as_of`, `scope`,
+    # `owner` and `dry_run` unusable as Dentaku variable names; `context:` is the escape
+    # hatch for a formula that genuinely declares one, and wins over the splat.
+    def calculate(key, as_of: nil, scope: nil, owner: nil, dry_run: false, context: {}, **extra)
+      EvaluateFormula.(
+        calculable: self,
+        key:,
+        scope: scope || calculator_scope_name,
+        owner: owner || calculator_owner,
+        as_of:,
+        context: extra.merge(context),
+        dry_run:
+      )
+    end
+
+    def calculate_as_of(key, as_of, **context)
+      calculate(key, as_of:, **context)
+    end
+
+    def calculation_history(key = nil, limit: nil)
+      runs = calculator_runs.recent_first
+      runs = runs.for_formula_key(key) unless key.nil?
+      limit.nil? ? runs : runs.limit(limit)
+    end
+
+    def calculator_owner
+      nil
+    end
+
+    # Chains a calculation and a render in one call — `calculate:` names one formula key
+    # (assigned as `result`) or several (assigned as `results`) — or renders a Result the
+    # caller already has. Leftover keywords splat into the template's assigns *and* into
+    # the calculation's context, so one call can feed both.
+    def render(key, calculate: nil, result: nil, results: {}, as_of: nil, scope: nil,
+               owner: nil, version_number: nil, dry_run: false, context: {}, **extra)
+      assigns = extra.merge(context)
+      computed = calculator_render_results(calculate, as_of:, scope:, owner:, dry_run:, context: assigns)
+
+      RenderTemplate.(
+        key:, version_number:, context: assigns,
+        scope: scope || calculator_scope_name,
+        owner: owner || calculator_owner,
+        result: result || (computed.values.first unless calculate.is_a?(Array)),
+        results: results.merge(computed)
+      )
+    end
+
+    private
+
+    # Forwards the assigns as `context:` rather than splatting them, so a key named
+    # `scope` reaches the formula instead of redirecting its lookup.
+    def calculator_render_results(keys, as_of:, scope:, owner:, dry_run:, context:)
+      Array(keys).to_h do |formula_key|
+        [formula_key.to_s, calculate(formula_key, as_of:, scope:, owner:, dry_run:, context:)]
+      end
+    end
+  end
+end

data/lib/acts_as_calculator/calculator_cache.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class CalculatorCache
+    def self.default
+      @default ||= new
+    end
+
+    def initialize(functions: FunctionRegistry.default)
+      @functions = functions
+      @key = :"acts_as_calculator_calculators_#{object_id}"
+    end
+
+    def fetch(formula_version_id)
+      raise ArgumentError, "a calculator cache key must be a formula_version_id" if formula_version_id.nil?
+
+      store[formula_version_id] ||= BuildCalculator.(functions:)
+    end
+
+    def clear
+      store.clear
+    end
+
+    private
+
+    attr_reader :functions, :key
+
+    # Keyed by formula_version_id because version content is immutable, so an entry can
+    # never go stale. Held per thread because Dentaku::Calculator mutates its own memory
+    # while evaluating — one shared instance across a Puma thread pool would interleave
+    # two requests' variables.
+    def store
+      Thread.current[key] ||= {}
+    end
+  end
+end

data/lib/acts_as_calculator/cast_date.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "date"
+
+module ActsAsCalculator
+  class CastDate
+    def self.call(value)
+      return value if value.instance_of?(Date)
+      return value.to_date if value.respond_to?(:to_date)
+
+      Date.parse(value.to_s)
+    rescue ArgumentError, TypeError, RangeError
+      raise Error, "cannot cast #{value.inspect} to a date"
+    end
+  end
+end