acts_as_calculator 0.1.0

data/lib/acts_as_calculator/render_liquid.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module ActsAsCalculator
+  # The security boundary. Template bodies are authored by non-developers (eventually
+  # through Phase 5's API), so this deliberately renders inside a private
+  # Liquid::Environment rather than Liquid's process-global default, which a host app is
+  # free to have repointed at a real file system or loaded its own tags into.
+  class RenderLiquid
+    # `include`/`render` are the only tags that read from outside the assigns. A
+    # BlankFileSystem already refuses them; dropping the tags means the template fails at
+    # parse time with a syntax error instead of at render time with a file system error.
+    FILE_SYSTEM_TAGS = %w[include render].freeze
+
+    # `tablerow` iterates a collection the same way `for` does, but through its own
+    # render_to_output_buffer rather than a subclassable collection_segment. It is a
+    # storefront grid-layout tag with no use in rendering a calculation, so it is dropped
+    # rather than given a second, version-fragile bounded subclass.
+    ITERATING_TAGS = %w[tablerow].freeze
+
+    # Bounds output size and assign churn. These do NOT bound iteration on their own —
+    # render_score counts rendered nodes, so an empty loop body scores zero per pass. That
+    # gap is closed by BoundedFor/MAX_ITERATIONS below, not here.
+    RESOURCE_LIMITS = {
+      render_length_limit: 2_000_000,
+      render_score_limit: 200_000,
+      assign_score_limit: 2_000_000
+    }.freeze
+
+    # Cumulative across every loop in one render, so nested loops multiply into the same
+    # budget instead of each staying under a per-loop cap. Generous for presenting a
+    # calculation; a template needing more than this is not a template.
+    MAX_ITERATIONS = 10_000
+
+    class IterationBudget
+      def initialize(limit)
+        @limit = limit
+        @remaining = limit
+      end
+
+      # Checked against the collection as declared, *before* Liquid reaches Range#to_a on
+      # it — `{% for i in (1..2000000000) %}` is a heap bomb no post-hoc count can undo.
+      def reserve(collection)
+        size = countable_size(collection)
+
+        exhausted! if !size.nil? && size > remaining
+      end
+
+      def spend(count)
+        @remaining -= count
+
+        exhausted! if remaining.negative?
+      end
+
+      private
+
+      attr_reader :limit, :remaining
+
+      def countable_size(collection)
+        case collection
+        when ::Range, ::Array, ::Hash then collection.size
+        end
+      end
+
+      # Liquid::MemoryError is the one exception BlockBody.rescue_render_node re-raises
+      # instead of routing through the error mode, so a resource bound reported this way
+      # cannot be swallowed into the rendered output.
+      def exhausted!
+        raise Liquid::MemoryError, "template exceeded #{limit} loop iterations"
+      end
+    end
+
+    class BoundedFor < Liquid::For
+      private
+
+      # The collection expression is evaluated once more than stock Liquid does, to size
+      # it before the superclass materialises it. Everything reachable from a template is
+      # a Drop, Hash or Array by construction, so re-evaluating is cheap and side-effect
+      # free.
+      def collection_segment(context)
+        budget = context.registers[:iteration_budget]
+        budget&.reserve(context.evaluate(@collection_name))
+
+        super.tap { |segment| budget&.spend(segment.length) }
+      end
+    end
+
+    SANDBOX_TAGS = Liquid::Tags::STANDARD_TAGS
+                   .reject { |name, _| (FILE_SYSTEM_TAGS + ITERATING_TAGS).include?(name) }
+                   .merge("for" => BoundedFor)
+                   .freeze
+
+    SANDBOX = Liquid::Environment.build(
+      error_mode: :strict,
+      file_system: Liquid::BlankFileSystem.new,
+      tags: SANDBOX_TAGS
+    ) do |environment|
+      environment.default_resource_limits = RESOURCE_LIMITS
+      environment.register_filter(LiquidFilters)
+    end
+
+    def self.call(source:, assigns: {})
+      Liquid::Template
+        .parse(source.to_s, environment: SANDBOX, line_numbers: true)
+        .render!(assigns,
+                 registers: { iteration_budget: IterationBudget.new(MAX_ITERATIONS) },
+                 strict_filters: true)
+    rescue Liquid::Error => e
+      raise TemplateRenderError, e.to_s
+    end
+  end
+end

data/lib/acts_as_calculator/render_template.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class RenderTemplate
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(key: nil, scope: nil, owner: nil, version_number: nil,
+                   template: nil, result: nil, results: {}, context: {})
+      @key = key
+      @scope = scope
+      @owner = owner
+      @version_number = version_number
+      @template = template
+      @result = result
+      @results = results
+      @context = context
+    end
+
+    def call
+      RenderLiquid.(source: template.body, assigns:)
+    end
+
+    private
+
+    attr_reader :key, :scope, :owner, :version_number, :result, :results, :context
+
+    def template
+      @template ||= ResolveTemplate.(key:, scope:, owner:, version_number:)
+    end
+
+    # Context is merged under the result assigns rather than over them: a host that happens
+    # to pass a `result` key in context must not be able to shadow the calculation the
+    # template exists to display.
+    def assigns
+      CastLiquidValue.(context).merge(
+        "result" => CastLiquidValue.(result),
+        "results" => CastLiquidValue.(results)
+      )
+    end
+  end
+end

data/lib/acts_as_calculator/resolve_formula_version.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class ResolveFormulaVersion
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(key:, scope: nil, owner: nil, as_of: nil)
+      @key = key.to_s
+      @scope = (scope || DEFAULT_SCOPE).to_s
+      @owner = owner
+      @as_of = CastDate.(as_of || Date.current)
+    end
+
+    def call
+      covering_version || raise_no_effective_version
+    end
+
+    private
+
+    attr_reader :key, :scope, :owner, :as_of
+
+    def formula
+      @formula ||= FindOwnedRecord.(relation: Formula.all, key:, scope:, owner:) || raise_formula_not_found
+    end
+
+    def covering_version
+      formula.versions.active.covering(as_of).order(effective_from: :desc, id: :desc).first
+    end
+
+    def raise_formula_not_found
+      raise FormulaNotFoundError, "no formula #{key.inspect} in scope #{scope.inspect} for #{describe_owner}"
+    end
+
+    # Deliberately not "fall back to the most recent active version" — that would apply
+    # today's rules to a date they were never in force for, which is the exact failure
+    # effective-dating exists to prevent (docs/PLAN.md, "Data model").
+    def raise_no_effective_version
+      raise NoEffectiveVersionError,
+            "formula #{key.inspect} in scope #{scope.inspect} has no active version " \
+            "covering #{as_of.iso8601} (versions: #{described_versions})"
+    end
+
+    def describe_owner
+      owner.nil? ? "no owner" : "#{owner.class}##{owner.id} (or globally)"
+    end
+
+    def described_versions
+      ranges = formula.versions.active.order(:effective_from).map do |version|
+        "#{version.effective_from.iso8601}..#{version.effective_to&.iso8601 || "open"}"
+      end
+
+      ranges.empty? ? "none active" : ranges.join(", ")
+    end
+  end
+end

data/lib/acts_as_calculator/resolve_import_owner.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # `{"owner": {"type": "Company", "id": 7}}` — omitted means the global (nil-owner) row,
+  # which is what a single-tenant host wants and what `FindOwnedRecord` falls back to.
+  class ResolveImportOwner
+    def self.call(reference)
+      return nil if reference.nil?
+
+      attributes = symbolize(reference)
+      model = model_for(attributes[:type])
+      id = attributes[:id]
+      raise ImportError, "owner reference #{reference.inspect} needs both a type and an id" if id.nil?
+
+      model.find_by(model.primary_key => id) ||
+        raise(ImportError, "no #{model.name} with id #{id.inspect} to own the imported record")
+    end
+
+    def self.symbolize(reference)
+      raise ImportError, "owner must be an object like {\"type\": \"Company\", \"id\": 1}" unless reference.is_a?(Hash)
+
+      reference.transform_keys(&:to_sym)
+    end
+    private_class_method :symbolize
+
+    # An import file is operator-authored, but it is still data — resolving an arbitrary
+    # string to a constant is only safe if the result is checked, not just loaded.
+    def self.model_for(type)
+      model = type.to_s.safe_constantize
+      unless model.is_a?(Class) && model < ::ActiveRecord::Base
+        raise ImportError, "owner type #{type.inspect} is not an ActiveRecord model"
+      end
+
+      model
+    end
+    private_class_method :model_for
+  end
+end

data/lib/acts_as_calculator/resolve_template.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class ResolveTemplate
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(key:, scope: nil, owner: nil, version_number: nil)
+      @key = key.to_s
+      @scope = (scope || DEFAULT_SCOPE).to_s
+      @owner = owner
+      @version_number = version_number
+    end
+
+    def call
+      FindOwnedRecord.(relation:, key:, scope:, owner:) || raise_template_not_found
+    end
+
+    private
+
+    attr_reader :key, :scope, :owner, :version_number
+
+    # Presentation, not an audited rule, so there is no effective-dating to resolve: the
+    # current version is whichever row carries the flag, and asking for a version_number
+    # pins an exact row for previewing or diffing one that isn't live.
+    def relation
+      version_number.nil? ? Template.current : Template.where(version_number:)
+    end
+
+    def raise_template_not_found
+      raise TemplateNotFoundError,
+            "no #{version_number.nil? ? "current" : "version #{version_number}"} template " \
+            "#{key.inspect} in scope #{scope.inspect} for #{describe_owner}"
+    end
+
+    def describe_owner
+      owner.nil? ? "no owner" : "#{owner.class}##{owner.id} (or globally)"
+    end
+  end
+end

data/lib/acts_as_calculator/resolve_variables.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class ResolveVariables
+    SOURCE_TYPES = %i[attribute method lookup context].freeze
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(specs:, calculable: nil, context: {}, lookups: {})
+      @specs = specs
+      @calculable = calculable
+      @context = context
+      @lookups = lookups
+    end
+
+    def call
+      variables.each_with_object({}) do |spec, inputs|
+        inputs[spec.name] = resolve(spec)
+      end
+    end
+
+    private
+
+    attr_reader :specs, :calculable, :context, :lookups
+
+    def variables
+      specs.map { |spec| VariableSpec.build(spec) }
+    end
+
+    def resolve(spec)
+      value = fetch(spec)
+      return value unless value.nil?
+      raise MissingVariableError, "required variable #{spec.name.inspect} resolved to nil" if spec.required
+
+      spec.default
+    end
+
+    def fetch(spec)
+      case spec.source_type
+      when :attribute then attribute_value(spec)
+      when :method then method_value(spec)
+      when :lookup then lookup_value(spec)
+      when :context then context_value(spec.source_config[:key] || spec.name)
+      else raise_unknown_source_type(spec)
+      end
+    end
+
+    def attribute_value(spec)
+      send_to_calculable(spec.source_config[:attribute] || spec.name)
+    end
+
+    def method_value(spec)
+      send_to_calculable(spec.source_config[:method] || spec.name, *Array(spec.source_config[:args]))
+    end
+
+    def send_to_calculable(name, *args)
+      return calculable.public_send(name, *args) if calculable.respond_to?(name)
+      return calculable[name] if args.empty? && calculable.respond_to?(:[])
+
+      raise_unreadable(name)
+    end
+
+    def raise_unreadable(name)
+      raise VariableResolutionError, "no calculable given to read #{name.inspect} from" if calculable.nil?
+
+      raise VariableResolutionError, "#{calculable.class} does not respond to #{name.inspect}"
+    end
+
+    def raise_unknown_source_type(spec)
+      raise UnknownSourceTypeError,
+            "unknown source_type #{spec.source_type.inspect} for #{spec.name.inspect} " \
+            "(known: #{SOURCE_TYPES.join(", ")})"
+    end
+
+    def lookup_value(spec)
+      tiers = tiers_for(spec.source_config[:table] || spec.name)
+      using = spec.source_config[:using]
+      return tiers if using.nil?
+
+      FindTier.(tiers:, amount: lookup_amount(using)).value
+    end
+
+    def lookup_amount(source)
+      return context_value(source) if context.key?(source.to_s) || context.key?(source.to_sym)
+
+      send_to_calculable(source)
+    end
+
+    def tiers_for(table)
+      lookups.fetch(table.to_s) do
+        lookups.fetch(table.to_sym) do
+          raise MissingLookupTableError, "no lookup table registered for #{table.inspect}"
+        end
+      end
+    end
+
+    def context_value(key)
+      return context[key.to_s] if context.key?(key.to_s)
+
+      context[key.to_sym]
+    end
+  end
+end

data/lib/acts_as_calculator/result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  Result = Data.define(:value, :breakdown, :formula_version, :as_of) do
+    def initialize(value:, breakdown: {}, formula_version: nil, as_of: nil)
+      super(value:, breakdown: deep_copy(breakdown), formula_version:, as_of:)
+    end
+
+    def inputs
+      breakdown.fetch(:inputs, {})
+    end
+
+    def expression
+      breakdown[:expression]
+    end
+
+    private
+
+    # Copies the containers rather than freezing them in place: the breakdown is built
+    # from the caller's own inputs hash, and freezing that would reach back out of the
+    # Result. Leaves are left alone for the same reason — a formula_version or a record
+    # passed through the breakdown stays the caller's to mutate.
+    def deep_copy(value)
+      case value
+      when Hash then value.to_h { |key, nested| [deep_copy(key), deep_copy(nested)] }.freeze
+      when Array then value.map { |nested| deep_copy(nested) }.freeze
+      when String then -value
+      else value
+      end
+    end
+  end
+end

data/lib/acts_as_calculator/result_drop.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module ActsAsCalculator
+  class ResultDrop < Liquid::Drop
+    def initialize(result)
+      super()
+      @result = result
+    end
+
+    def value
+      CastLiquidValue.(result.value)
+    end
+
+    def as_of
+      result.as_of
+    end
+
+    def expression
+      result.expression
+    end
+
+    def inputs
+      CastLiquidValue.(result.inputs)
+    end
+
+    def breakdown
+      CastLiquidValue.(result.breakdown)
+    end
+
+    def formula_version
+      version = result.formula_version
+
+      FormulaVersionDrop.new(version) unless version.nil?
+    end
+
+    def to_s
+      value.to_s
+    end
+
+    private
+
+    attr_reader :result
+  end
+end

data/lib/acts_as_calculator/serialize_formula.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Identity only by default — content lives on the versions, and a formulas index that
+  # inlined every version of every formula would be the wrong default for the one endpoint
+  # a host hits most.
+  class SerializeFormula
+    def self.call(formula:, versions: false)
+      payload = { id: formula.id, key: formula.key, scope: formula.scope,
+                  owner_type: formula.owner_type, owner_id: formula.owner_id,
+                  created_at: formula.created_at&.iso8601, updated_at: formula.updated_at&.iso8601 }
+      return payload unless versions
+
+      payload.merge(versions: formula.versions.order(:version_number)
+                                     .map { |version| SerializeFormulaVersion.(version:) })
+    end
+  end
+end

data/lib/acts_as_calculator/serialize_formula_version.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class SerializeFormulaVersion
+    def self.call(version:, variables: false)
+      payload = attributes(version)
+      return payload unless variables
+
+      payload.merge(variables: version.variables.order(:name).map { |variable| serialize_variable(variable) })
+    end
+
+    def self.attributes(version)
+      { id: version.id, formula_id: version.formula_id, version_number: version.version_number,
+        expression: version.expression, status: version.status, change_note: version.change_note,
+        effective_from: version.effective_from&.iso8601, effective_to: version.effective_to&.iso8601,
+        created_at: version.created_at&.iso8601, updated_at: version.updated_at&.iso8601 }
+    end
+    private_class_method :attributes
+
+    def self.serialize_variable(variable)
+      { id: variable.id, name: variable.name, source_type: variable.source_type,
+        source_config: variable.source_config, required: variable.required }
+    end
+    private_class_method :serialize_variable
+  end
+end

data/lib/acts_as_calculator/serialize_import_summary.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # The same per-entry report the rake task prints, as JSON: failures are per entry, so a
+  # caller has to be told which entries landed and which did not, not just that "the import
+  # failed".
+  class SerializeImportSummary
+    def self.call(summary:)
+      { source: summary.source,
+        success: summary.success?,
+        counts: summary.counts,
+        outcomes: summary.outcomes.map { |outcome| serialize_outcome(outcome) } }
+    end
+
+    def self.serialize_outcome(outcome)
+      { kind: outcome.kind, status: outcome.status, key: outcome.key,
+        scope: outcome.scope, detail: outcome.detail }
+    end
+    private_class_method :serialize_outcome
+  end
+end

data/lib/acts_as_calculator/serialize_template.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class SerializeTemplate
+    def self.call(template:)
+      { id: template.id, key: template.key, scope: template.scope,
+        owner_type: template.owner_type, owner_id: template.owner_id,
+        body: template.body, format: template.format,
+        version_number: template.version_number, current: template.current,
+        created_at: template.created_at&.iso8601, updated_at: template.updated_at&.iso8601 }
+    end
+  end
+end

data/lib/acts_as_calculator/supersede_formula_versions.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Makes room for a new active version. `FormulaVersion` refuses two active versions whose
+  # effective ranges overlap, so publishing a correction to a rule that is currently in
+  # force has to close the incumbent out first — by moving its `effective_to` or retiring
+  # it, never by touching its `expression`, which is what stays immutable.
+  #
+  # An incumbent is only ever superseded into a range the newcomer takes over. Where the
+  # newcomer would leave part of the incumbent's range with no rule at all, this raises:
+  # `effective_from` is immutable on an active version, so there is no way to keep just the
+  # tail, and quietly retiring the whole row would delete coverage a past calculation had.
+  # Same principle as the resolver's "no covering version raises, never fall back" — a gap
+  # the operator did not ask for is not this Decree's to create (docs/PLAN.md, "Data model").
+  class SupersedeFormulaVersions
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(formula:, effective_from:, effective_to: nil)
+      @formula = formula
+      @effective_from = CastDate.(effective_from)
+      @effective_to = effective_to && CastDate.(effective_to)
+    end
+
+    # Every incumbent is checked before any is written, so a refusal never leaves half the
+    # supersede applied.
+    def call
+      incumbents = overlapping
+      orphaned = incumbents.find { |version| !covers_tail_of?(version) }
+      raise PartialSupersedeError, uncovered_tail_message(orphaned) if orphaned
+
+      incumbents.each { |version| supersede(version) }
+    end
+
+    private
+
+    attr_reader :formula, :effective_from, :effective_to
+
+    def overlapping
+      versions = formula.versions.active
+      versions = versions.where(effective_from: ..effective_to) if effective_to
+
+      versions.open_ended_or_ending_on_or_after(effective_from).to_a
+    end
+
+    # An open-ended newcomer runs to the end of time, so nothing can outlast it.
+    def covers_tail_of?(version)
+      return true if effective_to.nil?
+
+      !version.effective_to.nil? && version.effective_to <= effective_to
+    end
+
+    # Starting on or after the newcomer leaves no range to shorten the incumbent to, so
+    # retiring is the only move — and by here the newcomer is known to cover all of it.
+    def supersede(version)
+      if version.effective_from >= effective_from
+        version.update!(status: FormulaVersion::RETIRED)
+      else
+        version.update!(effective_to: effective_from - 1)
+      end
+    end
+
+    def uncovered_tail_message(version)
+      tail = describe(effective_to + 1, version.effective_to)
+
+      "version #{version.version_number} of formula #{formula.key.inspect} is effective " \
+        "#{describe(version.effective_from, version.effective_to)}, which outlasts the new version's " \
+        "#{describe(effective_from, effective_to)}. Superseding it would leave #{tail} with no active " \
+        "version at all. Either extend the new version's effective_to to " \
+        "#{describe_bound(version.effective_to)}, or declare a version covering #{tail} first — entries " \
+        "are applied in order, so the one taking over the tail has to land before the one giving it up."
+    end
+
+    def describe(from, to)
+      "#{from.iso8601}..#{describe_bound(to)}"
+    end
+
+    def describe_bound(date)
+      date.nil? ? "open" : date.iso8601
+    end
+  end
+end

data/lib/acts_as_calculator/tier.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  Tier = Data.define(:from, :to, :value) do
+    def self.build(source)
+      return source if source.is_a?(Tier)
+
+      attributes = source.respond_to?(:to_h) ? source.to_h : read_from(source)
+      attributes = attributes.transform_keys(&:to_sym)
+
+      new(from: attributes[:from], to: attributes[:to], value: attributes[:value])
+    end
+
+    def self.read_from(source)
+      { from: source.from, to: source.to, value: source.value }
+    end
+    private_class_method :read_from
+
+    def covers?(amount)
+      amount >= lower_bound && amount < upper_bound
+    end
+
+    def lower_bound
+      from || -Float::INFINITY
+    end
+
+    def upper_bound
+      to || Float::INFINITY
+    end
+  end
+end