acts_as_calculator 0.1.0

data/lib/acts_as_calculator/import_definitions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # The one place import happens. Both authoring paths — the generator and the rake task —
+  # are argument parsing and printing around this call, so neither can drift into having
+  # its own idea of what "already imported" means.
+  class ImportDefinitions
+    # Lookup tables first: a formula version's variables name tables that have to resolve
+    # before a calculation using them can run.
+    SECTIONS = {
+      "lookup_tables" => ImportLookupTable,
+      "formulas" => ImportFormula,
+      "templates" => ImportTemplate
+    }.freeze
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(path: nil, data: nil)
+      raise ImportError, "give ImportDefinitions either a path or data, not both" if path && data
+      raise ImportError, "ImportDefinitions needs a path or data" if path.nil? && data.nil?
+
+      @path = path
+      @document = (data || ReadImportFile.(path)).transform_keys(&:to_s)
+    end
+
+    def call
+      reject_unknown_sections
+
+      ImportSummary.new(source: path&.to_s || "inline data", outcomes:)
+    end
+
+    private
+
+    attr_reader :path, :document
+
+    def outcomes
+      SECTIONS.flat_map do |section, decree|
+        Array(document[section]).map { |attributes| import(decree, attributes, section) }
+      end
+    end
+
+    def reject_unknown_sections
+      unknown = document.keys - SECTIONS.keys
+      return if unknown.empty?
+
+      raise ImportError, "unknown import section(s) #{unknown.join(", ")} (known: #{SECTIONS.keys.join(", ")})"
+    end
+
+    # One savepoint per entry, not one transaction per file: the summary reports what each
+    # entry did, so a half-written formula must not survive its own failure, and the twenty
+    # entries that imported cleanly must not be rolled back by the twenty-first.
+    def import(decree, attributes, section)
+      raise ImportError, "#{section} must be a list of objects, got #{attributes.inspect}" unless attributes.is_a?(Hash)
+
+      Record.transaction(requires_new: true) { decree.(attributes:) }
+    rescue Error, ::ActiveRecord::ActiveRecordError => e
+      failure(attributes, section, e)
+    end
+
+    def failure(attributes, section, error)
+      attributes = attributes.is_a?(Hash) ? attributes.transform_keys(&:to_s) : {}
+
+      ImportOutcome.build(kind: section.delete_suffix("s"), status: :failed,
+                          key: attributes["key"] || "(no key)", scope: attributes["scope"] || DEFAULT_SCOPE,
+                          detail: error.message)
+    end
+  end
+end

data/lib/acts_as_calculator/import_formula.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class ImportFormula
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(attributes:)
+      @attributes = attributes.transform_keys(&:to_s)
+      @key = @attributes.fetch("key") { raise ImportError, "a formulas entry has no key" }.to_s
+      @scope = (@attributes["scope"] || DEFAULT_SCOPE).to_s
+      @owner = ResolveImportOwner.(@attributes["owner"])
+    end
+
+    def call
+      return outcome(:created, add_version(Formula.create!(key:, scope:, owner:))) if formula.nil?
+      return outcome(:skipped, matching_version) if matching_version
+
+      outcome(:updated, add_version(formula))
+    end
+
+    private
+
+    attr_reader :attributes, :key, :scope, :owner
+
+    # The exact [key, scope, owner] triple, with none of `FindOwnedRecord`'s fallback to the
+    # global row: an owner-scoped import that quietly rewrote the global formula would be
+    # the opposite of what the file asked for.
+    def formula
+      return @formula if defined?(@formula)
+
+      @formula = Formula.owned_by(owner).find_by(key:, scope:)
+    end
+
+    # Content, not status: a file that flips a version from draft to active is asking to
+    # publish the version it already declared, not to write a second copy of it.
+    def matching_version
+      @matching_version ||= formula.versions.includes(:variables).find { |version| same_content?(version) }
+    end
+
+    def same_content?(version)
+      version.expression == expression &&
+        version.effective_from == effective_from &&
+        version.effective_to == effective_to &&
+        specs(version.variables) == declared_specs
+    end
+
+    def add_version(target)
+      PublishFormulaVersion.(formula: target, expression:, effective_from:, effective_to:, status:,
+                             change_note: attributes["change_note"], variables: declared_variables)
+    end
+
+    def expression
+      @expression ||= required_attribute("expression").to_s
+    end
+
+    def effective_from
+      @effective_from ||= CastDate.(required_attribute("effective_from"))
+    end
+
+    def effective_to
+      return @effective_to if defined?(@effective_to)
+
+      @effective_to = attributes["effective_to"] && CastDate.(attributes["effective_to"])
+    end
+
+    def status
+      @status ||= (attributes["status"] || FormulaVersion::ACTIVE).to_s
+    end
+
+    def required_attribute(name)
+      attributes.fetch(name) { raise ImportError, "formula #{key.inspect} has no #{name}" }
+    end
+
+    def declared_variables
+      @declared_variables ||= Array(attributes["variables"]).map { |variable| declared_variable(variable) }
+    end
+
+    def declared_variable(variable)
+      variable = variable.transform_keys(&:to_s)
+      variable.fetch("name") { raise ImportError, "formula #{key.inspect} has a variable with no name" }
+
+      CastVariableAttributes.(variable)
+    end
+
+    def declared_specs
+      @declared_specs ||= specs(declared_variables)
+    end
+
+    # `VariableSpec` already normalises a Hash and an AR `Variable` onto the same shape, so
+    # comparing through it is the same reading `ResolveVariables` gets at calculation time.
+    # Declaration order carries no meaning — a reordered file is the same formula.
+    def specs(variables)
+      variables.map { |variable| VariableSpec.build(variable) }.sort_by(&:name)
+    end
+
+    def outcome(result, version)
+      ImportOutcome.build(kind: :formula, status: result, key:, scope:, detail: "version #{version.version_number}")
+    end
+  end
+end

data/lib/acts_as_calculator/import_lookup_table.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class ImportLookupTable
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(attributes:)
+      @attributes = attributes.transform_keys(&:to_s)
+      @key = @attributes.fetch("key") { raise ImportError, "a lookup_tables entry has no key" }.to_s
+      @scope = (@attributes["scope"] || DEFAULT_SCOPE).to_s
+      @owner = ResolveImportOwner.(@attributes["owner"])
+    end
+
+    def call
+      return create if existing.nil?
+      return outcome(:skipped) if entries_unchanged?
+
+      guard_against_rewriting_audited_brackets
+      replace_entries
+      outcome(:updated)
+    end
+
+    private
+
+    attr_reader :attributes, :key, :scope, :owner
+
+    def existing
+      return @existing if defined?(@existing)
+
+      @existing = LookupTable.owned_by(owner).find_by(key:, scope:)
+    end
+
+    def create
+      table = LookupTable.create!(key:, scope:, owner:)
+      write_entries(table)
+      outcome(:created)
+    end
+
+    def replace_entries
+      existing.entries.destroy_all
+      write_entries(existing)
+    end
+
+    def write_entries(table)
+      declared_entries.each_with_index do |entry, position|
+        table.entries.create!(position:, from: entry[:from], to: entry[:to], value: entry[:value])
+      end
+    end
+
+    def declared_entries
+      @declared_entries ||= Array(attributes["entries"]).map { |entry| declared_entry(entry.transform_keys(&:to_s)) }
+    end
+
+    def declared_entry(entry)
+      value = entry.fetch("value") { raise ImportError, "lookup table #{key.inspect} has an entry with no value" }
+
+      { from: cast_bound(entry["from"]), to: cast_bound(entry["to"]), value: CastDecimal.(value) }
+    end
+
+    def cast_bound(value)
+      value.nil? ? nil : CastDecimal.(value)
+    end
+
+    def entries_unchanged?
+      existing.entries.ordered.map { |entry| { from: entry.from, to: entry.to, value: entry.value } } ==
+        declared_entries
+    end
+
+    # Entries a draft version merely mentions are still free to change; entries an active
+    # or retired version resolved are not, because a run has been audited against them.
+    def guard_against_rewriting_audited_brackets
+      statuses = [FormulaVersion::ACTIVE, FormulaVersion::RETIRED]
+      references = FindLookupTableReferences.(lookup_table: existing, statuses:)
+      return if references.empty?
+
+      raise LookupTableInUseError, in_use_message(references)
+    end
+
+    def in_use_message(references)
+      used_by = references.map { |version| "#{version.formula.key}##{version.version_number} (#{version.status})" }
+
+      "lookup table #{key.inspect} in scope #{scope.inspect} already backs #{used_by.join(", ")}; " \
+        "changing its entries would retroactively change what those calculations were audited " \
+        "against. Import a new table key instead (e.g. #{key.inspect} → \"#{key}_v2\") and a new " \
+        "formula version pointing at it."
+    end
+
+    def outcome(status)
+      ImportOutcome.build(kind: :lookup_table, status:, key:, scope:)
+    end
+  end
+end

data/lib/acts_as_calculator/import_outcome.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # One line of an import report: what was touched, and what happened to it.
+  IMPORT_STATUSES = %i[created updated skipped failed].freeze
+
+  ImportOutcome = Data.define(:kind, :status, :key, :scope, :detail) do
+    def self.build(kind:, status:, key:, scope:, detail: nil)
+      new(kind: kind.to_sym, status: status.to_sym, key: key.to_s, scope: scope.to_s, detail:)
+    end
+
+    def failed?
+      status == :failed
+    end
+
+    def to_s
+      "#{status} #{kind} #{key.inspect} (scope #{scope.inspect})#{detail && " — #{detail}"}"
+    end
+  end
+end

data/lib/acts_as_calculator/import_summary.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  ImportSummary = Data.define(:source, :outcomes) do
+    def success?
+      failures.empty?
+    end
+
+    def failures
+      outcomes.select(&:failed?)
+    end
+
+    def counts
+      IMPORT_STATUSES.to_h { |status| [status, outcomes.count { |outcome| outcome.status == status }] }
+    end
+
+    def to_s
+      [headline, *outcomes.map { |outcome| "  #{outcome}" }].join("\n")
+    end
+
+    private
+
+    def headline
+      tally = counts.map { |status, count| "#{count} #{status}" }.join(", ")
+
+      "acts_as_calculator: imported #{source} — #{tally}"
+    end
+  end
+end

data/lib/acts_as_calculator/import_template.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class ImportTemplate
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(attributes:)
+      @attributes = attributes.transform_keys(&:to_s)
+      @key = @attributes.fetch("key") { raise ImportError, "a templates entry has no key" }.to_s
+      @scope = (@attributes["scope"] || DEFAULT_SCOPE).to_s
+      @owner = ResolveImportOwner.(@attributes["owner"])
+    end
+
+    # An import publishes. The rake task's job is to make a deploy's templates the live
+    # ones; a version that imported but stayed staged would look like it had worked and
+    # render the previous body forever. Rollback stays `PromoteTemplate.(template: older)`,
+    # which the next import then reverses — the file is the source of truth.
+    def call
+      return outcome(:skipped, current) if current && current.body == body && current.format == format
+
+      outcome(versions.exists? ? :updated : :created, publish)
+    end
+
+    private
+
+    attr_reader :attributes, :key, :scope, :owner
+
+    def versions
+      Template.owned_by(owner).where(key:, scope:)
+    end
+
+    def current
+      return @current if defined?(@current)
+
+      @current = versions.current.first
+    end
+
+    def publish
+      PublishTemplate.(key:, scope:, owner:, body:, format:)
+    end
+
+    def body
+      @body ||= attributes.fetch("body") { raise ImportError, "template #{key.inspect} has no body" }.to_s
+    end
+
+    def format
+      @format ||= (attributes["format"] || Template::HTML).to_s
+    end
+
+    def outcome(result, template)
+      ImportOutcome.build(kind: :template, status: result, key:, scope:,
+                          detail: "version #{template.version_number}")
+    end
+  end
+end

data/lib/acts_as_calculator/liquid_filters.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+
+module ActsAsCalculator
+  # Registered on this gem's own Liquid::Environment, never on Liquid's global default, so
+  # a host app's other Liquid usage neither gains these nor loses its own `date` filter.
+  # Only public methods here become filters; the helpers below stay private on purpose.
+  module LiquidFilters
+    DELIMITER = ","
+    ISO_DATE = "%Y-%m-%d"
+
+    def currency(input, unit = "", precision = 2)
+      return "" if blank_input?(input)
+
+      places = Integer(precision)
+      "#{unit}#{delimited(FunctionRegistry::ROUND_CURRENCY.(numeric(input), places), places)}"
+    end
+
+    # Takes a rate expressed as a fraction of one — the form this gem's bracket tiers and
+    # lookup tables hold — so 0.2205 renders as "22.05%".
+    def percentage(input, precision = 2)
+      return "" if blank_input?(input)
+
+      places = Integer(precision)
+      "#{delimited(FunctionRegistry::ROUND_CURRENCY.(numeric(input) * 100, places), places)}%"
+    end
+
+    def date(input, format = ISO_DATE)
+      point = time_like(input)
+
+      point.nil? ? "" : point.strftime(format.to_s)
+    end
+
+    private
+
+    def blank_input?(input)
+      input.nil? || input == ""
+    end
+
+    def numeric(input)
+      CastDecimal.(input.is_a?(ResultDrop) ? input.value : input)
+    end
+
+    def delimited(decimal, places)
+      whole, fraction = decimal.abs.to_s("F").split(".")
+      grouped = whole.reverse.scan(/\d{1,3}/).join(DELIMITER).reverse
+      sign = decimal.negative? ? "-" : ""
+
+      places.positive? ? "#{sign}#{grouped}.#{fraction.to_s.ljust(places, "0")[0, places]}" : "#{sign}#{grouped}"
+    end
+
+    def time_like(input)
+      case input
+      when nil, "" then nil
+      when ::Date, ::Time then input
+      when ::Integer then ::Time.at(input)
+      when ::String then parsed_date(input)
+      else input if input.respond_to?(:strftime)
+      end
+    end
+
+    def parsed_date(input)
+      ::Date.parse(input)
+    rescue ::Date::Error
+      nil
+    end
+  end
+end

data/lib/acts_as_calculator/persist_run.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class PersistRun
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(calculable:, formula_version:, result:, as_of: nil)
+      @calculable = calculable
+      @formula_version = formula_version
+      @result = result
+      @as_of = CastDate.(as_of || result.as_of || Date.current)
+    end
+
+    def call
+      Run.create!(
+        calculable:,
+        formula_version:,
+        as_of_date: as_of,
+        inputs: CastJsonSafe.(result.inputs),
+        breakdown: CastJsonSafe.(result.breakdown),
+        result: result.value
+      )
+    end
+
+    private
+
+    attr_reader :calculable, :formula_version, :result, :as_of
+  end
+end

data/lib/acts_as_calculator/promote_template.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Rollback. Pointing `current` at an older row leaves every version in place, which is
+  # what "simple version history for rollback" (docs/PLAN.md) buys over deleting the row
+  # that went wrong or racing MAX(version_number).
+  class PromoteTemplate
+    def self.call(template:)
+      Template.transaction do
+        Template.version_siblings_of(template).current.where.not(id: template.id)
+                .update_all(current: false, updated_at: Time.current)
+        # A caller's copy of an already-demoted row still reads `current == true` in memory
+        # — publishing a newer version demotes it with update_all — so without this the
+        # write below looks like a no-op change and never reaches the database.
+        template.reload.update!(current: true)
+      end
+
+      template
+    end
+  end
+end

data/lib/acts_as_calculator/publish_formula_version.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Adding a version is never just an insert. `FormulaVersion` refuses two active versions
+  # whose effective ranges overlap, so publishing a rule that replaces one already in force
+  # has to supersede the incumbent first — and `SupersedeFormulaVersions` refuses outright
+  # where that would leave part of the incumbent's range uncovered.
+  #
+  # Every authoring path goes through here (JSON import, the API), so none of them can grow
+  # its own idea of what replacing a rule means or of how version numbers are handed out.
+  class PublishFormulaVersion
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(formula:, expression:, effective_from:, effective_to: nil,
+                   status: FormulaVersion::ACTIVE, change_note: nil, variables: [])
+      @formula = formula
+      @expression = expression.to_s
+      @effective_from = CastDate.(effective_from)
+      @effective_to = effective_to && CastDate.(effective_to)
+      @status = status.to_s
+      @change_note = change_note
+      @variables = Array(variables).map { |variable| CastVariableAttributes.(variable) }
+    end
+
+    # `requires_new` so this is one unit of work even when the caller already has a
+    # transaction open: a rejected variable must not leave behind a version claiming to
+    # declare it, and a supersede must not outlive the version it made room for. A caller
+    # that rescues and carries on is exactly the case a joined transaction would not cover.
+    def call
+      Record.transaction(requires_new: true) do
+        SupersedeFormulaVersions.(formula:, effective_from:, effective_to:) if status == FormulaVersion::ACTIVE
+
+        create_version
+      end
+    end
+
+    private
+
+    attr_reader :formula, :expression, :effective_from, :effective_to, :status, :change_note, :variables
+
+    def create_version
+      version = formula.versions.create!(version_number: next_version_number, expression:,
+                                         effective_from:, effective_to:, status:, change_note:)
+      variables.each { |variable| version.variables.create!(**variable) }
+      version
+    end
+
+    def next_version_number
+      (formula.versions.maximum(:version_number) || 0) + 1
+    end
+  end
+end

data/lib/acts_as_calculator/publish_template.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  # Authoring a template body publishes it: a new row, numbered one past its siblings, with
+  # the outgoing version demoted by the model's own before_create hook. Never `update!` on
+  # an existing row and never `update_all(current:)` — the one-current-version index refuses
+  # the latter, and the former would rewrite a version the history exists to keep.
+  # Rollback is `PromoteTemplate`, not deleting the row that went wrong.
+  class PublishTemplate
+    def self.call(key:, body:, scope: nil, owner: nil, format: Template::HTML)
+      template = Template.new(key: key.to_s, scope: (scope || DEFAULT_SCOPE).to_s, owner:,
+                              body: body.to_s, format: format.to_s, current: true)
+      template.version_number = template.next_version_number
+      template.save!
+      template
+    end
+  end
+end

data/lib/acts_as_calculator/read_import_file.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ActsAsCalculator
+  class ReadImportFile
+    def self.call(path)
+      raise ImportError, "no import file at #{path}" unless File.file?(path.to_s)
+
+      parse(File.read(path.to_s), path)
+    end
+
+    def self.parse(source, path)
+      document = JSON.parse(source)
+      return document if document.is_a?(Hash)
+
+      raise ImportError, "#{path} must contain a JSON object, got #{document.class}"
+    rescue JSON::ParserError => e
+      raise ImportError, "#{path} is not valid JSON: #{e.message}"
+    end
+    private_class_method :parse
+  end
+end