generalis 0.1.0

data/lib/generalis.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_support/core_ext'
+
+require_relative 'generalis/config'
+require_relative 'generalis/version'
+
+module Generalis
+  autoload :Account, 'generalis/account'
+  autoload :Accountable, 'generalis/accountable'
+  autoload :Asset, 'generalis/asset'
+  autoload :Expense, 'generalis/expense'
+  autoload :Liability, 'generalis/liability'
+  autoload :Revenue, 'generalis/revenue'
+
+  autoload :Transaction, 'generalis/transaction'
+  autoload :Link, 'generalis/link'
+  autoload :Linkable, 'generalis/linkable'
+
+  autoload :Entry, 'generalis/entry'
+  autoload :Credit, 'generalis/credit'
+  autoload :Debit, 'generalis/debit'
+
+  # @return [Hash{String => Integer}]
+  def self.trial_balances
+    subquery = Entry
+      .group(:account_id, :currency)
+      .select(Entry.arel_table[:id].maximum)
+
+    Entry
+      .joins(:account)
+      .where(id: subquery)
+      .group(:currency)
+      .sum((Entry.arel_table[:balance_after_cents] * Account.arel_table[:coefficient]))
+  end
+
+  # @return [Config]
+  def self.config
+    @config ||= Config.new.freeze
+  end
+
+  # @return [void]
+  def self.configure
+    config = Config.new
+    yield(config)
+
+    @config = config.freeze
+  end
+
+  # @return [String]
+  def self.table_name_prefix
+    config.table_name_prefix
+  end
+end

data/lib/generators/factory_bot/templates/transactions.rb.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :<%= factory_name %>, class: '<%= qualified_class_name %>' do
+    type { '<%= qualified_class_name %>' }
+  end
+end

data/lib/generators/factory_bot/transaction_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module FactoryBot
+  module Generators
+    class TransactionGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      def create_transaction_factory
+        template 'transactions.rb.erb', "spec/factories/#{module_path}/#{file_name}.rb"
+      end
+
+      def file_name
+        class_name.underscore.pluralize
+      end
+
+      def qualified_class_name
+        "#{module_name}::#{class_name}"
+      end
+
+      def class_name
+        "#{name.to_s.classify.chomp('Transaction')}Transaction"
+      end
+
+      def module_name
+        module_path.classify
+      end
+
+      def module_path
+        'ledger'
+      end
+
+      def factory_name
+        class_name.underscore
+      end
+    end
+  end
+end

data/lib/generators/generalis/install_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Generalis
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer
+        template 'generalis.rb', 'config/initializers/generalis.rb'
+      end
+
+      def create_base_transaction
+        template 'base_transaction.rb', 'app/models/ledger/base_transaction.rb'
+      end
+    end
+  end
+end

data/lib/generators/generalis/migrations_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Generalis
+  module Generators
+    class MigrationsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_files
+        migration_template 'create_ledger_accounts.rb.erb', 'db/migrate/create_ledger_accounts.rb'
+        migration_template 'create_ledger_transactions.rb.erb', 'db/migrate/create_ledger_transactions.rb'
+        migration_template 'create_ledger_entries.rb.erb', 'db/migrate/create_ledger_entries.rb'
+        migration_template 'create_ledger_links.rb.erb', 'db/migrate/create_ledger_links.rb'
+      end
+
+      def json_column_type
+        case ActiveRecord::Base.connection.adapter_name
+        when 'SQLite'     then ':string'
+        when 'MySQL'      then ':json'
+        when 'PostgreSQL' then ':jsonb'
+        else
+          Rails.logger.warn('Unsupported database adapter; using String for JSON data types')
+
+          ':string'
+        end
+      end
+
+    private
+
+      # @param name [Symbol, String]
+      # @return [String]
+      def prefixed_table_name(name)
+        ":#{Generalis.table_name_prefix}#{name}"
+      end
+    end
+  end
+end

data/lib/generators/generalis/templates/base_transaction.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ledger
+  class BaseTransaction < Generalis::Transaction
+    extend DSL
+    extend Links
+
+    self.abstract_class = true
+
+    validates :type, presence: true
+  end
+end

data/lib/generators/generalis/templates/create_ledger_accounts.rb.erb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateLedgerAccounts < ActiveRecord::Migration[6.1]
+  def change
+    create_table <%= prefixed_table_name(:accounts) %> do |t|
+      t.string     :type, null: false
+      t.belongs_to :owner, null: true, polymorphic: true
+      t.string     :name, null: false
+      t.integer    :coefficient, null: false
+      t.timestamps default: -> { 'NOW()' }
+
+      t.check_constraint 'coefficient IN (-1, +1)'
+
+      t.index %i[owner_type owner_id name], unique: true
+      t.index :name, unique: true, where: 'owner_id IS NULL'
+    end
+  end
+end

data/lib/generators/generalis/templates/create_ledger_entries.rb.erb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class CreateLedgerEntries < ActiveRecord::Migration[6.1]
+  def change
+    create_table <%= prefixed_table_name(:entries) %> do |t|
+      t.string     :type, null: false
+      t.belongs_to :account, null: false, foreign_key: { to_table: <%= prefixed_table_name(:accounts) %> }
+      t.belongs_to :transaction, null: false, foreign_key: { to_table: <%= prefixed_table_name(:transactions) %> }
+      t.uuid       :pair_id, null: true
+      t.string     :currency, null: false
+      t.integer    :amount_cents, null: false
+      t.integer    :balance_after_cents, null: false
+      t.integer    :coefficient, null: false
+      t.column     :metadata, <%= json_column_type %>
+      t.timestamps default: -> { 'NOW()' }
+
+      t.check_constraint 'amount_cents >= 0'
+      t.check_constraint 'coefficient IN (-1, +1)'
+
+      t.index %i[transaction_id pair_id]
+      # Index for efficiently selecting the latest balance on the account.
+      t.index %i[account_id currency id], order: { id: :desc }
+    end
+  end
+end

data/lib/generators/generalis/templates/create_ledger_links.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class CreateLedgerLinks < ActiveRecord::Migration[6.1]
+  def change
+    create_table <%= prefixed_table_name(:links) %> do |t|
+      t.belongs_to :transaction, null: false, foreign_key: { on_delete: :cascade, to_table: <%= prefixed_table_name(:transactions) %> }
+      t.belongs_to :linkable, polymorphic: true, null: false
+      t.string     :name, null: false
+      t.timestamps default: -> { 'NOW()' }
+
+      t.index %i[transaction_id name]
+    end
+  end
+end

data/lib/generators/generalis/templates/create_ledger_transactions.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class CreateLedgerTransactions < ActiveRecord::Migration[6.1]
+  def change
+    create_table <%= prefixed_table_name(:transactions) %> do |t|
+      t.string     :type
+      t.string     :transaction_id, null: false, index: { unique: true }
+      t.string     :description
+      t.column     :metadata, <%= json_column_type %>
+      t.timestamp  :occurred_at, null: false, default: -> { 'NOW()' }
+      t.timestamps default: -> { 'NOW()' }
+    end
+  end
+end

data/lib/generators/generalis/templates/generalis.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Generalis.configure do |config|
+  # Set a custom database table name prefix for Generalis models.
+  # config.table_name_prefix = 'ledger_'
+end

data/lib/generators/generalis/templates/transaction.rb.erb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class <%= module_name %>::<%= class_name %> < Ledger::BaseTransaction
+  transaction_id do
+    # TODO: Generate a transaction ID
+  end
+
+  description do
+    # Optional: Provide a description of the transaction
+  end
+
+  occurred_at do
+    # Optional: Include a timestamp for the transaction (defaults to now)
+  end
+
+  metadata do
+    # Optional: Any additional metadata to be stored with the transaction (an Array or Hash)
+  end
+
+  double_entry do |e|
+    # TODO: Define entries
+    # e.debit  = Generalis::Asset[:cash]
+    # e.credit = customer.accounts_receivable
+    # e.amount = 100.00
+  end
+end

data/lib/generators/generalis/transaction_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Generalis
+  module Generators
+    class TransactionGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      def create_transaction
+        template 'transaction.rb.erb', "app/models/#{module_path}/#{file_name}.rb"
+      end
+
+      def file_name
+        class_name.underscore
+      end
+
+      def class_name
+        "#{name.to_s.classify.chomp('Transaction')}Transaction"
+      end
+
+      def module_name
+        module_path.classify
+      end
+
+      def module_path
+        'ledger'
+      end
+
+      hook_for :test_framework
+    end
+  end
+end

data/lib/generators/rspec/templates/transaction_spec.rb.erb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= qualified_class_name %>, type: :model do
+  subject(:transaction) { build(:<%= factory_name %>) }
+
+  it 'has a valid factory' do
+    expect(transaction).to be_valid
+  end
+end

data/lib/generators/rspec/transaction_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Rspec
+  module Generators
+    class TransactionGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      def create_transaction_spec
+        template 'transaction_spec.rb.erb', "spec/models/#{module_path}/#{file_name}.rb"
+      end
+
+      def file_name
+        "#{class_name.underscore}_spec"
+      end
+
+      def qualified_class_name
+        "#{module_name}::#{class_name}"
+      end
+
+      def class_name
+        "#{name.to_s.classify.chomp('Transaction')}Transaction"
+      end
+
+      def module_name
+        module_path.classify
+      end
+
+      def module_path
+        'ledger'
+      end
+
+      def factory_name
+        class_name.underscore
+      end
+
+      hook_for :fixture_replacement
+    end
+  end
+end

data/lib/rspec/change_balance_of_matcher.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/resolve_account_helper'
+require_relative 'helpers/resolve_amount_helper'
+
+RSpec::Matchers.define :change_balance_of do |account, owner: nil|
+  include Generalis::RSpec::ResolveAccountHelper
+  include Generalis::RSpec::ResolveAmountHelper
+
+  match do |transaction|
+    transaction.prepare
+
+    account = resolve_account(account, owner: owner)
+    entries = transaction.entries.select { |entry| entry.account == account }
+
+    entries.any? && matches_amount?(entries)
+  end
+
+  chain(:by) do |amount, currency = nil|
+    @amount = resolve_amount(amount, currency)
+  end
+
+  # @param entries [Array<Generalis::Entry>]
+  # @return [Boolean]
+  def matches_amount?(entries)
+    return entries.group_by(&:currency).values.any? { |bucket| bucket.sum(&:net_amount).nonzero? } if @amount.nil?
+
+    entries
+      .select { |entry| entry.currency.casecmp(@amount.currency).zero? }
+      .sum(&:net_amount) == @amount
+  end
+end

data/lib/rspec/credit_account_matcher.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/format_helper'
+require_relative 'helpers/resolve_account_helper'
+require_relative 'helpers/resolve_amount_helper'
+
+RSpec::Matchers.define :credit_account do |account, owner: nil|
+  include Generalis::RSpec::FormatHelper
+  include Generalis::RSpec::ResolveAccountHelper
+  include Generalis::RSpec::ResolveAmountHelper
+
+  match do |transaction|
+    transaction.prepare
+
+    @account = resolve_account(account, owner: owner)
+    entries = transaction.entries.select { |entry| entry.credit? && entry.account == @account }
+
+    entries.any? && matches_amount?(entries)
+  end
+
+  chain(:with_amount) do |amount, currency = nil|
+    @amount = resolve_amount(amount, currency)
+  end
+
+  failure_message do |transaction|
+    message  = "expected transaction to credit account #{format_account(@account)}"
+    message += " with amount #{format_money(@amount)}" if @amount
+    message += "\n"
+    message += "\nCredits:\n"
+    message += transaction.entries.select(&:credit?).map { |entry| format_entry(entry) }.join("\n")
+    message += "\nDebits:\n"
+    message += transaction.entries.select(&:debit?).map { |entry| format_entry(entry) }.join("\n")
+    message
+  end
+
+  # @param entries [Array<Generalis::Entry>]
+  # @return [Boolean]
+  def matches_amount?(entries)
+    return true if @amount.nil?
+
+    entries
+      .select { |entry| entry.currency.casecmp(@amount.currency).zero? }
+      .sum(&:amount) == @amount
+  end
+end

data/lib/rspec/debit_account_matcher.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/format_helper'
+require_relative 'helpers/resolve_account_helper'
+require_relative 'helpers/resolve_amount_helper'
+
+RSpec::Matchers.define :debit_account do |account, owner: nil|
+  include Generalis::RSpec::FormatHelper
+  include Generalis::RSpec::ResolveAccountHelper
+  include Generalis::RSpec::ResolveAmountHelper
+
+  match do |transaction|
+    transaction.prepare
+
+    @account = resolve_account(account, owner: owner)
+    entries = transaction.entries.select { |entry| entry.debit? && entry.account == @account }
+
+    entries.any? && matches_amount?(entries)
+  end
+
+  chain(:with_amount) do |amount, currency = nil|
+    @amount = resolve_amount(amount, currency)
+  end
+
+  failure_message do |transaction|
+    message  = "expected transaction to debit account #{format_account(@account)}"
+    message += " with amount #{format_money(@amount)}" if @amount
+    message += "\n"
+    message += "\nCredits:\n"
+    message += transaction.entries.select(&:credit?).map { |entry| format_entry(entry) }.join("\n")
+    message += "\nDebits:\n"
+    message += transaction.entries.select(&:debit?).map { |entry| format_entry(entry) }.join("\n")
+    message
+  end
+
+  # @param entries [Array<Generalis::Entry>]
+  # @return [Boolean]
+  def matches_amount?(entries)
+    return true if @amount.nil?
+
+    entries
+      .select { |entry| entry.currency.casecmp(@amount.currency).zero? }
+      .sum(&:amount) == @amount
+  end
+end

data/lib/rspec/have_balance_matcher.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/format_helper'
+require_relative 'helpers/resolve_account_helper'
+require_relative 'helpers/resolve_amount_helper'
+
+RSpec::Matchers.define :have_balance do |amount, currency = nil|
+  include Generalis::RSpec::FormatHelper
+  include Generalis::RSpec::ResolveAccountHelper
+  include Generalis::RSpec::ResolveAmountHelper
+
+  match do |account, owner: nil|
+    @account = resolve_account(account, owner: owner)
+    @amount  = resolve_amount(amount, currency)
+
+    values_match?(@account.balance(@amount.currency.to_s), @amount)
+  end
+
+  failure_message do
+    message = "expected #{format_account(@account)} to have balance #{format_money(@amount)}\n"
+    message + "\tactual balance was #{format_money(@account.balance(@amount.currency.to_s))}"
+  end
+
+  failure_message_when_negated do
+    "expected #{format_account(@account)} not to have balance #{format_money(@amount)}"
+  end
+end

data/lib/rspec/helpers/format_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Generalis
+  module RSpec
+    module FormatHelper
+      # @param entry [Generalis::Entry]
+      # @return [String]
+      def format_entry(entry)
+        "\t#{format_money(entry.amount)} to #{format_account(entry.account)}"
+      end
+
+      # @param account [Generalis::Account]
+      # @return [String]
+      def format_account(account)
+        text  = "#{account.class}[:#{account.name}]"
+        text += " (Owner: #{account.owner.class} #{account.owner.id})" if account.owner
+
+        text
+      end
+
+      # @param money [Money]
+      # @return [String]
+      def format_money(money)
+        "#{money.format} (#{money.currency})"
+      end
+    end
+  end
+end

data/lib/rspec/helpers/resolve_account_helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Generalis
+  module RSpec
+    module ResolveAccountHelper
+      # @param location [Symbol, String, Generalis::Account]
+      # @param owner [ActiveRecord::Base, nil]
+      # @return [Generalis::Account]
+      def resolve_account(locator, owner:)
+        case locator
+        when Generalis::Account
+          locator
+        when String, Symbol
+          Generalis::Account.lookup(locator, owner: owner)
+        else
+          raise ArgumentError, "Expected a Generalis::Account, String, or Symbol, got #{account.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/rspec/helpers/resolve_amount_helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Generalis
+  module RSpec
+    module ResolveAmountHelper
+      # @param amount [Money, Numeric]
+      # @param currency [String, nil]
+      # @return [Money]
+      def resolve_amount(amount, currency = nil)
+        case amount
+        when Money
+          amount
+        when Numeric
+          Money.from_amount(amount, currency)
+        else
+          raise ArgumentError, "Expected Money or Numeric, got #{amount.inspect}"
+        end
+      end
+    end
+  end
+end