acts_as_calculator 0.1.0

data/lib/acts_as_calculator/variable_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  VariableSpec = Data.define(:name, :source_type, :source_config, :required) do
+    def self.build(source)
+      attributes = source.is_a?(Hash) ? source : read_from(source)
+      attributes = attributes.transform_keys(&:to_sym)
+      required = attributes[:required]
+      required = true if required.nil?
+
+      new(
+        name: attributes.fetch(:name).to_s,
+        source_type: (attributes[:source_type] || :context).to_sym,
+        source_config: (attributes[:source_config] || {}).transform_keys(&:to_sym),
+        required:
+      )
+    end
+
+    def self.read_from(source)
+      {
+        name: source.name,
+        source_type: source.source_type,
+        source_config: source.source_config,
+        required: source.respond_to?(:required) ? source.required : true
+      }
+    end
+    private_class_method :read_from
+
+    def default
+      source_config[:default]
+    end
+  end
+end

data/lib/acts_as_calculator/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  VERSION = "0.1.0"
+end

data/lib/acts_as_calculator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "dentaku"
+require "liquid"
+
+require_relative "acts_as_calculator/version"
+require_relative "acts_as_calculator/errors"
+require_relative "acts_as_calculator/configuration"
+require_relative "acts_as_calculator/cast_decimal"
+require_relative "acts_as_calculator/result"
+require_relative "acts_as_calculator/tier"
+require_relative "acts_as_calculator/variable_spec"
+require_relative "acts_as_calculator/find_tier"
+require_relative "acts_as_calculator/function_registry"
+require_relative "acts_as_calculator/build_calculator"
+require_relative "acts_as_calculator/evaluate_expression"
+require_relative "acts_as_calculator/resolve_variables"
+require_relative "acts_as_calculator/divide_proportionally"
+require_relative "acts_as_calculator/distribute_remainder"
+require_relative "acts_as_calculator/apportionment"
+require_relative "acts_as_calculator/apportion_amount"
+require_relative "acts_as_calculator/aggregation"
+require_relative "acts_as_calculator/aggregate_results"
+require_relative "acts_as_calculator/formula_version_drop"
+require_relative "acts_as_calculator/result_drop"
+require_relative "acts_as_calculator/cast_liquid_value"
+require_relative "acts_as_calculator/liquid_filters"
+require_relative "acts_as_calculator/render_liquid"
+
+module ActsAsCalculator
+  # The scope every formula, lookup table and template falls into when a host doesn't
+  # namespace one. A non-null column beats a nullable one here because uniqueness is
+  # scoped on `[key, scope, owner_type, owner_id]` and NULLs never compare equal.
+  DEFAULT_SCOPE = "default"
+
+  # Defined here rather than in engine.rb because Engine.isolate_namespace only leaves
+  # this alone if the module already answers to it — otherwise it installs an
+  # `on_load(:active_record)` hook that redefines it to "acts_as_calculator_" long after
+  # the engine class body has run. The tables are named for what they hold.
+  def self.table_name_prefix
+    "calculator_"
+  end
+end
+
+require_relative "acts_as_calculator/cast_date"
+require_relative "acts_as_calculator/cast_json_safe"
+require_relative "acts_as_calculator/calculator_cache"
+require_relative "acts_as_calculator/find_owned_record"
+require_relative "acts_as_calculator/build_lookups"
+require_relative "acts_as_calculator/resolve_formula_version"
+require_relative "acts_as_calculator/persist_run"
+require_relative "acts_as_calculator/evaluate_formula"
+require_relative "acts_as_calculator/resolve_template"
+require_relative "acts_as_calculator/promote_template"
+require_relative "acts_as_calculator/render_template"
+require_relative "acts_as_calculator/import_outcome"
+require_relative "acts_as_calculator/import_summary"
+require_relative "acts_as_calculator/read_import_file"
+require_relative "acts_as_calculator/resolve_import_owner"
+require_relative "acts_as_calculator/find_lookup_table_references"
+require_relative "acts_as_calculator/supersede_formula_versions"
+require_relative "acts_as_calculator/cast_variable_attributes"
+require_relative "acts_as_calculator/publish_formula_version"
+require_relative "acts_as_calculator/publish_template"
+require_relative "acts_as_calculator/import_lookup_table"
+require_relative "acts_as_calculator/import_formula"
+require_relative "acts_as_calculator/import_template"
+require_relative "acts_as_calculator/import_definitions"
+require_relative "acts_as_calculator/serialize_formula_version"
+require_relative "acts_as_calculator/serialize_formula"
+require_relative "acts_as_calculator/serialize_template"
+require_relative "acts_as_calculator/serialize_import_summary"
+
+# Everything above is plain Ruby and stays loadable without Rails; the two below are the
+# only files that touch a framework, so they load only when one is already present.
+require_relative "acts_as_calculator/calculable" if defined?(::ActiveSupport)
+require_relative "acts_as_calculator/engine" if defined?(::Rails::Engine)

data/lib/generators/acts_as_calculator/import/import_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ActsAsCalculator
+  module Generators
+    # A thin wrapper: read the path, hand it to ImportDefinitions, print what happened.
+    # Deliberately no `source_root` and no templates — this generator writes rows, not files.
+    class ImportGenerator < ::Rails::Generators::Base
+      desc "Imports formulas, lookup tables and templates from a JSON file. Idempotent: " \
+           "re-importing an unchanged file changes nothing, and changed content becomes a " \
+           "new version rather than an edit to an existing one."
+
+      argument :path, type: :string, desc: "Path to the JSON import file"
+
+      def import
+        summary = ImportDefinitions.(path: File.expand_path(path, destination_root))
+        say summary.to_s
+
+        raise Thor::Error, "acts_as_calculator: #{summary.failures.size} import error(s)" unless summary.success?
+      rescue ActsAsCalculator::Error => e
+        raise Thor::Error, "acts_as_calculator: #{e.message}"
+      end
+    end
+  end
+end

data/lib/generators/acts_as_calculator/install/install_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActsAsCalculator
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copies the acts_as_calculator migration for the six calculator_* tables."
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template "create_acts_as_calculator_tables.rb.tt",
+                           "db/migrate/create_acts_as_calculator_tables.rb"
+      end
+
+      private
+
+      def migration_version
+        "[#{::ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/acts_as_calculator/install/templates/create_acts_as_calculator_tables.rb.tt

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+class CreateActsAsCalculatorTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :calculator_formulas do |t|
+      t.string :key, null: false
+      t.string :scope, null: false, default: "default"
+      t.references :owner, polymorphic: true, null: true, index: false
+      t.timestamps
+    end
+    add_index :calculator_formulas, %i[key scope owner_type owner_id],
+              unique: true, name: "idx_calc_formulas_on_key_scope_owner"
+    add_index :calculator_formulas, %i[owner_type owner_id], name: "idx_calc_formulas_on_owner"
+
+    create_table :calculator_formula_versions do |t|
+      t.bigint :formula_id, null: false
+      t.integer :version_number, null: false
+      t.text :expression, null: false
+      t.date :effective_from, null: false
+      t.date :effective_to
+      t.string :status, null: false, default: "draft"
+      t.text :change_note
+      t.timestamps
+    end
+    add_index :calculator_formula_versions, %i[formula_id version_number],
+              unique: true, name: "idx_calc_versions_on_formula_and_number"
+    add_index :calculator_formula_versions, %i[formula_id status effective_from effective_to],
+              name: "idx_calc_versions_on_effective_range"
+    add_foreign_key :calculator_formula_versions, :calculator_formulas, column: :formula_id
+
+    create_table :calculator_variables do |t|
+      t.bigint :formula_version_id, null: false
+      t.string :name, null: false
+      t.string :source_type, null: false
+      t.column :source_config, json_type, null: false, default: {}
+      t.boolean :required, null: false, default: true
+      t.timestamps
+    end
+    add_index :calculator_variables, %i[formula_version_id name],
+              unique: true, name: "idx_calc_variables_on_version_and_name"
+    add_foreign_key :calculator_variables, :calculator_formula_versions, column: :formula_version_id
+
+    create_table :calculator_lookup_tables do |t|
+      t.string :key, null: false
+      t.string :scope, null: false, default: "default"
+      t.references :owner, polymorphic: true, null: true, index: false
+      t.timestamps
+    end
+    add_index :calculator_lookup_tables, %i[key scope owner_type owner_id],
+              unique: true, name: "idx_calc_lookup_tables_on_key_scope_owner"
+    add_index :calculator_lookup_tables, %i[owner_type owner_id], name: "idx_calc_lookup_tables_on_owner"
+
+    create_table :calculator_lookup_table_entries do |t|
+      t.bigint :lookup_table_id, null: false
+      t.integer :position, null: false, default: 0
+      t.decimal :from, precision: 20, scale: 6
+      t.decimal :to, precision: 20, scale: 6
+      t.decimal :value, precision: 20, scale: 6, null: false
+      t.timestamps
+    end
+    add_index :calculator_lookup_table_entries, %i[lookup_table_id position],
+              name: "idx_calc_lookup_entries_on_table_and_position"
+    add_foreign_key :calculator_lookup_table_entries, :calculator_lookup_tables, column: :lookup_table_id
+
+    create_table :calculator_templates do |t|
+      t.string :key, null: false
+      t.string :scope, null: false, default: "default"
+      t.references :owner, polymorphic: true, null: true, index: false
+      t.text :body, null: false
+      t.string :format, null: false, default: "html"
+      t.integer :version_number, null: false, default: 1
+      # Defaults to true so authoring a new version publishes it; rollback is pointing
+      # `current` back at an older row, which keeps the newer one in the history.
+      t.boolean :current, null: false, default: true
+      t.timestamps
+    end
+    add_index :calculator_templates, %i[key scope owner_type owner_id version_number],
+              unique: true, name: "idx_calc_templates_on_key_scope_owner_version"
+    add_index :calculator_templates, %i[owner_type owner_id], name: "idx_calc_templates_on_owner"
+
+    create_table :calculator_runs do |t|
+      t.references :calculable, polymorphic: true, null: false, index: false
+      t.bigint :formula_version_id, null: false
+      t.date :as_of_date, null: false
+      t.column :inputs, json_type, null: false, default: {}
+      t.column :breakdown, json_type, null: false, default: {}
+      t.decimal :result, precision: 30, scale: 10, null: false
+      t.timestamps
+    end
+    add_index :calculator_runs, %i[calculable_type calculable_id as_of_date],
+              name: "idx_calc_runs_on_calculable_and_date"
+    add_index :calculator_runs, :formula_version_id, name: "idx_calc_runs_on_formula_version"
+    add_foreign_key :calculator_runs, :calculator_formula_versions, column: :formula_version_id
+
+    add_global_uniqueness :calculator_formulas, %i[key scope], "idx_calc_formulas_global_key_scope"
+    add_global_uniqueness :calculator_lookup_tables, %i[key scope], "idx_calc_lookup_tables_global_key_scope"
+    add_global_uniqueness :calculator_templates, %i[key scope version_number],
+                          "idx_calc_templates_global_key_scope_version"
+
+    add_single_current_template
+  end
+
+  private
+
+  # Exactly one version of a template may be current per [key, scope, owner]. Both halves
+  # are needed for the same reason as add_global_uniqueness: the composite index cannot
+  # constrain rows whose owner_id is NULL, so globally-owned templates get their own.
+  def add_single_current_template
+    return unless connection.supports_partial_index?
+
+    add_index :calculator_templates, %i[key scope owner_type owner_id],
+              unique: true, where: "current = TRUE", name: "idx_calc_templates_one_current"
+    add_index :calculator_templates, %i[key scope],
+              unique: true, where: "current = TRUE AND owner_id IS NULL",
+              name: "idx_calc_templates_one_current_global"
+  end
+
+  # A composite unique index over a nullable owner does not constrain globally-owned rows
+  # at all: NULLs never compare equal, so two `owner_id IS NULL` rows with the same key
+  # both slip past it. A partial index closes that on every adapter that has one; the
+  # model-level uniqueness validation is the only guard on the rest.
+  def add_global_uniqueness(table, columns, name)
+    return unless connection.supports_partial_index?
+
+    add_index table, columns, unique: true, where: "owner_id IS NULL", name: name
+  end
+
+  # jsonb is Postgres-only; every other adapter Rails ships gets its own json type, which
+  # for sqlite3 and older MySQL is text with JSON casting on top.
+  def json_type
+    connection.adapter_name.match?(/postgres/i) ? :jsonb : :json
+  end
+end

data/lib/tasks/acts_as_calculator.rake

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+namespace :acts_as_calculator do
+  desc "Imports formulas, lookup tables and templates from a JSON file " \
+       "(rake acts_as_calculator:import[config/calculator/payroll.json])"
+  task :import, [:path] => :environment do |_task, args|
+    path = args[:path]
+    abort("usage: rake acts_as_calculator:import[path/to/file.json]") if path.nil? || path.empty?
+
+    begin
+      summary = ActsAsCalculator::ImportDefinitions.(path:)
+    rescue ActsAsCalculator::Error => e
+      abort("acts_as_calculator: #{e.message}")
+    end
+
+    puts summary
+    # Non-zero on any failed entry so a deploy or CI step stops here rather than shipping a
+    # half-imported rule set.
+    abort("acts_as_calculator: #{summary.failures.size} import error(s)") unless summary.success?
+  end
+end

data/sig/acts_as_calculator.rbs

@@ -0,0 +1,4 @@
+module ActsAsCalculator
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,251 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_calculator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- lautarograc
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: dentaku
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Mix Calculable into any model to get effective-dated, versioned formulas,
+  apportionment and aggregation helpers, and Liquid-rendered output — reusable across
+  payroll, e-commerce, and insurance domains.
+email:
+- lautarograciani2106@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/acts_as_calculator/application_controller.rb
+- app/controllers/acts_as_calculator/formula_versions_controller.rb
+- app/controllers/acts_as_calculator/formulas_controller.rb
+- app/controllers/acts_as_calculator/imports_controller.rb
+- app/controllers/acts_as_calculator/templates_controller.rb
+- app/models/acts_as_calculator/formula.rb
+- app/models/acts_as_calculator/formula_version.rb
+- app/models/acts_as_calculator/lookup_table.rb
+- app/models/acts_as_calculator/lookup_table_entry.rb
+- app/models/acts_as_calculator/record.rb
+- app/models/acts_as_calculator/run.rb
+- app/models/acts_as_calculator/template.rb
+- app/models/acts_as_calculator/variable.rb
+- config/routes.rb
+- lib/acts_as_calculator.rb
+- lib/acts_as_calculator/aggregate_results.rb
+- lib/acts_as_calculator/aggregation.rb
+- lib/acts_as_calculator/apportion_amount.rb
+- lib/acts_as_calculator/apportionment.rb
+- lib/acts_as_calculator/build_calculator.rb
+- lib/acts_as_calculator/build_lookups.rb
+- lib/acts_as_calculator/calculable.rb
+- lib/acts_as_calculator/calculator_cache.rb
+- lib/acts_as_calculator/cast_date.rb
+- lib/acts_as_calculator/cast_decimal.rb
+- lib/acts_as_calculator/cast_json_safe.rb
+- lib/acts_as_calculator/cast_liquid_value.rb
+- lib/acts_as_calculator/cast_variable_attributes.rb
+- lib/acts_as_calculator/configuration.rb
+- lib/acts_as_calculator/distribute_remainder.rb
+- lib/acts_as_calculator/divide_proportionally.rb
+- lib/acts_as_calculator/engine.rb
+- lib/acts_as_calculator/errors.rb
+- lib/acts_as_calculator/evaluate_expression.rb
+- lib/acts_as_calculator/evaluate_formula.rb
+- lib/acts_as_calculator/find_lookup_table_references.rb
+- lib/acts_as_calculator/find_owned_record.rb
+- lib/acts_as_calculator/find_tier.rb
+- lib/acts_as_calculator/formula_version_drop.rb
+- lib/acts_as_calculator/function_registry.rb
+- lib/acts_as_calculator/import_definitions.rb
+- lib/acts_as_calculator/import_formula.rb
+- lib/acts_as_calculator/import_lookup_table.rb
+- lib/acts_as_calculator/import_outcome.rb
+- lib/acts_as_calculator/import_summary.rb
+- lib/acts_as_calculator/import_template.rb
+- lib/acts_as_calculator/liquid_filters.rb
+- lib/acts_as_calculator/persist_run.rb
+- lib/acts_as_calculator/promote_template.rb
+- lib/acts_as_calculator/publish_formula_version.rb
+- lib/acts_as_calculator/publish_template.rb
+- lib/acts_as_calculator/read_import_file.rb
+- lib/acts_as_calculator/render_liquid.rb
+- lib/acts_as_calculator/render_template.rb
+- lib/acts_as_calculator/resolve_formula_version.rb
+- lib/acts_as_calculator/resolve_import_owner.rb
+- lib/acts_as_calculator/resolve_template.rb
+- lib/acts_as_calculator/resolve_variables.rb
+- lib/acts_as_calculator/result.rb
+- lib/acts_as_calculator/result_drop.rb
+- lib/acts_as_calculator/serialize_formula.rb
+- lib/acts_as_calculator/serialize_formula_version.rb
+- lib/acts_as_calculator/serialize_import_summary.rb
+- lib/acts_as_calculator/serialize_template.rb
+- lib/acts_as_calculator/supersede_formula_versions.rb
+- lib/acts_as_calculator/tier.rb
+- lib/acts_as_calculator/variable_spec.rb
+- lib/acts_as_calculator/version.rb
+- lib/generators/acts_as_calculator/import/import_generator.rb
+- lib/generators/acts_as_calculator/install/install_generator.rb
+- lib/generators/acts_as_calculator/install/templates/create_acts_as_calculator_tables.rb.tt
+- lib/tasks/acts_as_calculator.rake
+- sig/acts_as_calculator.rbs
+homepage: https://github.com/lautarograc/acts_as_calculator
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/lautarograc/acts_as_calculator
+  source_code_uri: https://github.com/lautarograc/acts_as_calculator
+  changelog_uri: https://github.com/lautarograc/acts_as_calculator/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/lautarograc/acts_as_calculator/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: A pricing and calculation engine on top of Dentaku.
+test_files: []