mudrat_projector 0.9.0

data/lib/mudrat_projector/transaction_entry.rb

@@ -0,0 +1,126 @@
+module MudratProjector
+  class TransactionEntry
+    attr :account_id, :scalar
+
+    module TransactionEntry::Factory
+      def new params = {}
+        catch :instance do
+          maybe_build_new_fixed_entry params
+          maybe_build_new_percentage_entry params
+          super
+        end
+      end
+
+      def new_credit params = {}
+        params = { credit_or_debit: :credit }.merge params
+        new params
+      end
+
+      def new_debit params = {}
+        params = { credit_or_debit: :debit }.merge params
+        new params
+      end
+
+      private
+
+      def maybe_build_new_fixed_entry params
+        return unless params.has_key? :amount
+        params = params.dup
+        params[:scalar] = params.delete :amount
+        throw :instance, new(params).tap(&:calculate)
+      end
+
+      def maybe_build_new_percentage_entry params
+        return unless params.has_key?(:percent) && self == TransactionEntry
+        params = params.dup
+        params[:scalar] = params.delete :percent
+        params[:other_account_id] = params.delete :of
+        throw :instance, PercentageTransactionEntry.new(params)
+      end
+    end
+
+    extend TransactionEntry::Factory
+
+    attr :amount, :delta
+
+    def initialize params = {}
+      @account_id      = params.fetch :account_id
+      @scalar          = params.fetch :scalar
+      @credit_or_debit = params.fetch :credit_or_debit
+      validate!
+    end
+
+    def * multiplier
+      return self if multiplier == 1
+      self.class.new serialize.merge(scalar: scalar * multiplier)
+    end
+
+    def calculate chart_of_accounts = nil
+      @amount = calculate_amount chart_of_accounts
+      return if chart_of_accounts.nil?
+      account_type = chart_of_accounts.fetch(account_id).type
+      check = %i(asset expense).include?(account_type) ? :debit? : :credit?
+      @delta = send(check) ? amount : -amount
+    end
+
+    def calculate_amount chart_of_accounts
+      @amount = scalar
+    end
+
+    def credit?
+      @credit_or_debit == :credit
+    end
+
+    def debit?
+      @credit_or_debit == :debit
+    end
+
+    def inspect
+      "#<#{self.class}: amount=#{fmt(scalar)}, account_id=#{account_id.inspect} type=#{@credit_or_debit.inspect}>"
+    end
+
+    def serialize
+      {
+        account_id:       account_id,
+        scalar:           scalar,
+        credit_or_debit:  @credit_or_debit,
+      }
+    end
+
+    def validate!
+      if scalar == 0
+        raise ArgumentError, "You cannot supply a scalar of 0"
+      end
+      unless %i(credit debit).include? @credit_or_debit
+        raise ArgumentError, "Must supply :credit or :debit, not #{@credit_or_debit.inspect}"
+      end
+    end
+
+    private
+
+    def fmt number
+      number.respond_to?(:round) ? number.round(2).to_f : number
+    end
+  end
+
+  class PercentageTransactionEntry < TransactionEntry
+    attr :other_account_id
+
+    def initialize params = {}
+      @other_account_id = params.fetch :other_account_id
+      super params
+    end
+
+    def calculate_amount chart_of_accounts
+      @amount = scalar * chart_of_accounts.fetch(other_account_id).balance
+    end
+
+    def inspect
+      "#<#{self.class}: percent=#{fmt(scalar * 100)}%, account_id=#{account_id.inspect} type=#{@credit_or_debit.inspect}, other_account_id=#{other_account_id.inspect}>"
+    end
+
+    def serialize
+      super.tap do |hash| hash[:other_account_id] = other_account_id; end
+    end
+  end
+end

data/lib/mudrat_projector/transaction_handler.rb

@@ -0,0 +1,19 @@
+module MudratProjector
+  class TransactionHandler
+    attr_accessor :next_projector
+
+    def initialize projection: projection
+      @projection = projection
+    end
+
+    def << transaction
+      in_projection, leftover = transaction.slice @projection.range.end
+      @projection.add_transaction_batch in_projection
+      defer leftover if leftover
+    end
+
+    def defer transaction
+      next_projector.add_transaction transaction if next_projector
+    end
+  end
+end

data/lib/mudrat_projector/validator.rb

@@ -0,0 +1,49 @@
+module MudratProjector
+  class Validator
+    attr :chart, :projector
+
+    def initialize projector: projector, chart: chart
+      @projector = projector
+      @chart     = chart
+    end
+
+    def must_be_balanced!
+      unless projector.balanced?
+        raise Projector::BalanceError, "Cannot project unless the accounts "\
+          "are in balance"
+      end
+    end
+
+    def validate_account! account_id, params
+      if chart.exists? account_id
+        raise Projector::AccountExists, "Account #{account_id.inspect} exists"
+      end
+      unless Account::TYPES.include? params[:type]
+        raise Projector::InvalidAccount, "Account #{account_id.inspect} has "\
+          "invalid type #{params[:type].inspect}"
+      end
+      if params.has_key?(:open_date) && params[:open_date] > projector.from
+        if params.has_key? :opening_balance
+          raise Projector::InvalidAccount, "Account #{account_id.inspect} opens "\
+            "after projector, but has an opening balance"
+        end
+      end
+    end
+
+    def validate_transaction! transaction
+      if transaction.date < projector.from
+        raise Projector::InvalidTransaction, "Transactions cannot occur before "\
+          "projection start date. (#{projector.from} vs. #{transaction.date})"
+      end
+      unless transaction.balanced?
+        raise Projector::BalanceError, "Credits and debit entries both "\
+          "must be supplied; they cannot amount to zero"
+      end
+      if transaction.credits.empty? || transaction.debits.empty?
+        raise Projector::InvalidTransaction, "You must supply at least a debit "\
+          "and a credit on each transaction"
+      end
+    end
+
+  end
+end

data/lib/mudrat_projector/version.rb

@@ -0,0 +1,3 @@
+module MudratProjector
+  VERSION = "0.9.0"
+end

data/lib/mudrat_projector.rb

@@ -0,0 +1,27 @@
+require "bigdecimal"
+require "bigdecimal/util"
+require "date"
+require "forwardable"
+require "yaml"
+
+require "mudrat_projector/version"
+
+module MudratProjector
+  ABSOLUTE_START = Date.new 1970
+  ABSOLUTE_END   = Date.new 9999
+
+  def self.classify sym
+    "_#{sym}".gsub %r{_[a-z]} do |bit|
+      bit.slice! 0, 1
+      bit.upcase!
+      bit
+    end
+  end
+
+  Dir.glob File.expand_path("../mudrat_projector/**/*.rb", __FILE__) do |path|
+    base_without_ext =  File.basename path, ".*"
+    klass_name       = classify base_without_ext
+    relative_path    = File.join "mudrat_projector", base_without_ext
+    autoload klass_name, relative_path
+  end
+end

data/mudrat_projector.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mudrat_projector/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mudrat_projector"
+  spec.version       = MudratProjector::VERSION
+  spec.authors       = ["ntl"]
+  spec.email         = ["nathanladd+github@gmail.com"]
+  spec.description   = %q{Mudrat Projector is a simple financial projection engine.}
+  spec.summary       = %q{Mudrat Projector is a simple financial projection engine designed for personal finance computations.}
+  spec.homepage      = "https://github.com/ntl/mudrat-projector"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "minitest-reporters"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "timecop"
+end

data/test/integrations/long_term_projection_test.rb

@@ -0,0 +1,42 @@
+require 'test_helper'
+
+class LongTermProjectiontest < Minitest::Test
+  def setup
+    @projector = Projector.new from: jan_1_2012
+    @projector.add_account :checking,   type: :asset
+    @projector.add_account :job,        type: :revenue, tags: %i(salary)
+    @projector.add_account :investment, type: :asset
+    @projector.add_account :dividends,  type: :revenue, tags: %i(dividend)
+
+    @projector.add_transaction(
+      date: jan_1_2012,
+      credit: { amount: 6000, account_id: :job },
+      debit:  { amount: 6000, account_id: :checking },
+      schedule: every_month,
+    )
+    @projector.add_transaction(
+      date: jan_1_2012,
+      credit: { percent: (6 / 1200.to_d), of: :investment, account_id: :dividends },
+      debit:  { percent: (6 / 1200.to_d), of: :investment, account_id: :investment },
+      schedule: every_month,
+    )
+    @projector.add_transaction(
+      date: jan_1_2012,
+      credit: { amount: 500, account_id: :checking },
+      debit:  { amount: 500, account_id: :investment },
+      schedule: every_month,
+    )
+
+    @household = { filing_status: :single, exemptions: 1 }
+  end
+
+  def test_two_years
+    projector = TaxCalculator.project @projector, to: dec_31_2013, household: @household
+
+    # used http://investor.gov/tools/calculators/compound-interest-calculator
+    assert_in_epsilon 715.98, projector.account_balance(:dividends)
+    expected_gross = 72000 + 72000 + 715.98
+    expected_taxes = 15702.45 + 17073.80
+    assert_in_epsilon expected_gross - expected_taxes, projector.net_worth
+  end
+end

data/test/integrations/mortgage_test.rb

@@ -0,0 +1,85 @@
+require 'test_helper'
+
+class MortgageTest < Minitest::Test
+  def setup
+    @loan_amount       = 200_000
+    @home_value        = 250_000
+    @down_payment      = @home_value - @loan_amount
+
+    @interest_rate     = 5.0.to_d
+    @property_tax_rate = 1.25.to_d
+    @loan_term         = 30
+    @start_date        = jan_1_2012
+
+    @projector = Projector.new from: jan_1_2012
+
+    @projector.add_account :checking, type: :asset,     opening_balance: 50000
+    @projector.add_account :job,      type: :revenue,   opening_balance: 50000
+    @projector.add_account :home,     type: :asset,     open_date: feb_1_2012
+    @projector.add_account :mortgage, type: :liability, open_date: feb_1_2012
+    @projector.add_account :interest, type: :expense,   open_date: feb_1_2012
+
+    @projector.add_transaction(
+      date: jan_1_2012,
+      credit: { amount: 6000, account_id: :job },
+      debit:  { amount: 6000, account_id: :checking },
+      schedule: { unit: :month, scalar: 1 },
+    )
+
+    @projector.add_transaction(
+      date: feb_1_2012,
+      credits: [{ amount: @down_payment, account_id: :checking },
+                { amount: @loan_amount,  account_id: :mortgage }],
+      debit:    { amount: @home_value,   account_id: :home     },
+    )
+  end
+
+  def test_balance_after_first_year
+    pay_off_loan years: 30
+    @projector.project to: dec_31_2012
+    assert_in_epsilon 197_300.83, @projector.account_balance(:mortgage).to_f
+  end
+
+  def test_net_worth_after_first_year
+    expected_checking_balance = 72000 - (9110.90 + 2699.17)
+    expected_net_worth = expected_checking_balance + @home_value - 197_300.83
+
+    pay_off_loan years: 30
+    @projector.project to: dec_31_2012
+
+    assert_in_epsilon expected_net_worth, @projector.net_worth
+  end
+
+  def test_mortgage_balances_to_zero_at_end_of_term
+    pay_off_loan years: 30
+    @projector.project to: jan_31_2042
+    assert_in_epsilon 0, @projector.account_balance(:mortgage)
+  end
+
+  def test_pay_off_mortgage_early
+    pay_off_loan years: 15
+    @projector.project to: jan_31_2027
+    assert_in_epsilon 0, @projector.account_balance(:mortgage)
+  end
+
+  private
+
+  def calculate_monthly_payment r, years = @loan_term
+    x  = (1 + r) ** (years * 12)
+    mp = (@loan_amount * r * x) / (x - 1)
+  end
+
+  def pay_off_loan years: @loan_term
+    r  = @interest_rate / 1200
+    mp = calculate_monthly_payment r, years
+
+    @projector.add_transaction(
+      date: feb_1_2012,
+      credits: [{ percent: r, of: :mortgage, account_id: :mortgage},
+                { amount: mp, account_id: :checking }],
+      debits:  [{ amount: mp, account_id: :mortgage },
+                { percent: r, of: :mortgage, account_id: :interest}],
+      schedule: { unit: :month, scalar: 1, count: (years * 12) },
+    )
+  end
+end

data/test/integrations/self_employed_tax_calculation_test.rb

@@ -0,0 +1,44 @@
+require 'test_helper'
+
+# http://taxes.about.com/od/paymentoptions/a/estimated_tax_3.htm
+class SelfEmployedTaxCalculationTest < Minitest::Test
+  def setup
+    @projector = Projector.new from: jan_1_2013
+
+    @projector.accounts = {
+      checking:     { type: :asset },
+      se_expenses:  { type: :expense, tags: %i(self_employed) },
+      se_job:       { type: :revenue, tags: %i(self_employed) },
+    }
+
+    @projector.transactions = [{
+      date:     jan_1_2013,
+      credit:   { amount: 25000 / 3.0.to_d, account_id: :se_job    },
+      debit:    { amount: 25000 / 3.0.to_d, account_id: :checking  },
+      schedule: every_month,
+    },{
+      date:     jan_1_2013,
+      credit:   { amount: 7500 / 3.0.to_d, account_id: :checking    },
+      debit:    { amount: 7500 / 3.0.to_d, account_id: :se_expenses },
+      schedule: every_month,
+    }]
+  end
+
+  def test_shelley
+    @tax_calculator = TaxCalculator.new projector: @projector, household: single
+    calculation = @tax_calculator.calculate!
+    assert_in_epsilon 70000,    calculation.total_income
+    assert_in_epsilon 9890.685, calculation.self_employment_tax
+    assert_in_epsilon 4945.34,  calculation.adjustments
+    assert_in_epsilon 65054.66, calculation.agi
+    assert_in_epsilon 55054.66, calculation.taxable_income 
+    assert_in_epsilon 9692.50,  calculation.income_tax
+    assert_in_epsilon 19583.19, calculation.taxes
+  end
+
+  private
+
+  def single
+    { filing_status: :single, exemptions: 1 }
+  end
+end

data/test/models/accounts_test.rb

@@ -0,0 +1,39 @@
+require 'test_helper'
+
+class AccountTest < Minitest::Test
+  def setup
+    @chart = ChartOfAccounts.new
+    @account = @chart.add_account :foo, type: :asset
+  end
+
+  # Closed means "are the books closed?", e.g. are there any transactions that
+  # haven't been processed
+  def test_closed_returns_true_iff_no_transaction_entries
+    assert @account.closed?
+    add_transaction_entry
+    refute @account.closed?
+  end
+
+  def test_close_freezes_and_returns_account_if_closed
+    new_account = @account.close!
+
+    assert @account.frozen?
+    assert_equal new_account.object_id, @account.object_id
+  end
+
+  def test_close_freezes_and_returns_new_closed_account_if_unclosed
+    add_transaction_entry
+    new_account = @account.close!
+
+    assert @account.frozen?
+    refute_equal new_account.object_id, @account.object_id
+  end
+
+  private
+
+  def add_transaction_entry
+    entry = TransactionEntry.new_debit account_id: :foo, amount: 1
+    entry.calculate @chart
+    @account.add_entry entry
+  end
+end

data/test/models/chart_of_accounts_test.rb

@@ -0,0 +1,170 @@
+require 'test_helper'
+
+class ChartOfAccountsTest < Minitest::Test
+  def setup
+    @chart = ChartOfAccounts.new
+  end
+
+  def test_can_add_an_account
+    @chart.add_account :checking, type: :asset, open_date: jan_1_2000
+    assert_equal 1, @chart.size
+  end
+
+  def test_adding_account_can_default_open_date
+    @chart.add_account :checking, type: :asset
+    assert_equal 1, @chart.size
+    assert_equal ABSOLUTE_START, @chart.fetch(:checking).open_date
+  end
+
+  def test_can_set_opening_balance
+    @chart.add_account :checking, type: :asset, opening_balance: 500
+    assert_equal [500], @chart.map(&:balance)
+  end
+
+  def test_balanced_iff_opening_balances_zero_out
+    assert_equal 0, @chart.balance
+    @chart.add_account :checking, type: :asset, opening_balance: 500
+    assert_equal 500, @chart.balance
+    @chart.add_account :slush, type: :equity, opening_balance: 500
+    assert_equal 0, @chart.balance
+  end
+
+  def test_can_tag
+    @chart.add_account :checking, type: :asset, tags: %i(foo)
+    assert @chart.fetch(:checking).tag? :foo
+  end
+
+  def test_can_add_a_child_account
+    @chart.add_account :my_bank, type: :asset
+    @chart.split_account :my_bank, into: %i(checking)
+  end
+
+  def test_can_add_a_child_account_with_opening_balances
+    @chart.add_account :my_bank, type: :asset, opening_balance: 200
+    @chart.split_account :my_bank, into: { checking: { amount: 50 }, savings: { amount: 150 }}
+    assert_equal 200, @chart.fetch(:my_bank).balance
+    assert_equal 50, @chart.fetch(:checking).balance
+    assert_equal 150, @chart.fetch(:savings).balance
+    assert_equal 200, @chart.balance
+  end
+
+  def test_can_add_a_child_account_with_tags
+    @chart.add_account :my_bank, type: :asset, tags: %i(foo)
+    @chart.split_account :my_bank, into: [:checking, [:savings, { tags: %i(bar) }]]
+    assert @chart.fetch(:checking).tag? :foo
+    refute @chart.fetch(:checking).tag? :bar
+    assert @chart.fetch(:savings).tag? :foo
+    assert @chart.fetch(:savings).tag? :bar
+  end
+
+  def test_net_worth
+    add_smattering_of_accounts
+    # Net worth is assets minus liabilities
+    assert_equal (25 + 400 + 15000) - (13000), @chart.net_worth
+  end
+
+  def test_applying_fixed_transaction
+    @chart.add_account :checking, type: :asset
+    @chart.add_account :job, type: :revenue
+
+    fixed_transaction = Transaction.new(
+      date: jan_1_2000,
+      debits:  [{ amount: 1234, account_id: :checking, credit_or_debit: :debit },
+                { amount: 12,   account_id: :job,      credit_or_debit: :debit }],
+      credits: [{ amount: 1234, account_id: :job,      credit_or_debit: :credit},
+                { amount: 12,   account_id: :checking, credit_or_debit: :credit}],
+    )
+
+    @chart.apply_transaction fixed_transaction
+    assert_equal 1222, @chart.net_worth
+  end
+
+  def test_applying_transaction_with_percentages
+    @chart.add_account :checking, type: :asset
+    @chart.add_account :investment, type: :asset, opening_balance: 200000
+    @chart.add_account :investment_revenue, type: :revenue
+
+    percentage_transaction = Transaction.new(
+      date: dec_31_2000,
+      debit:  { percent: 0.06, of: :investment, account_id: :checking,           credit_or_debit: :debit },
+      credit: { percent: 0.06, of: :investment, account_id: :investment_revenue, credit_or_debit: :credit },
+    )
+
+    @chart.apply_transaction percentage_transaction
+    assert_equal 212000, @chart.net_worth
+    assert_equal 12000, @chart.fetch(:checking).balance
+  end
+
+  def test_applying_transaction_for_non_existent_or_future_accounts_raises_error
+    @chart.add_account :checking, type: :asset, open_date: jan_1_2000
+    @chart.add_account :job, type: :revenue
+
+    transaction = Transaction.new(
+      date: jan_2_2000,
+      debit:  { amount: 1234, account_id: :no_existe, credit_or_debit: :debit },
+      credit: { amount: 1234, account_id: :job,       credit_or_debit: :credit },
+    )
+
+    assert_raises Projector::AccountDoesNotExist do
+      @chart.apply_transaction transaction
+    end
+  end
+
+  def test_serialize
+    add_smattering_of_accounts
+    expected_hash = {
+      checking: { type: :asset,     opening_balance: 25    },
+      savings:  { type: :asset,     opening_balance: 400   },
+      auto:     { type: :asset,     opening_balance: 15000 },
+      bills:    { type: :expense,   opening_balance: 26    },
+      car_loan: { type: :liability, opening_balance: 13000 },
+      new_job:  { type: :revenue,   opening_balance: 500   },
+    }
+    assert_equal expected_hash.keys, @chart.serialize.keys
+    expected_hash.each do |key, expected_value|
+      assert_equal expected_value, @chart.serialize.fetch(key)
+    end
+    assert_equal expected_hash, @chart.serialize
+  end
+
+  def test_account_balance_with_splits
+    @chart.add_account :my_bank, type: :asset
+    @chart.add_account :job, type: :revenue
+    @chart.split_account :my_bank, into: %i(checking savings)
+    @chart.split_account :checking, into: %i(checking_1 checking_2)
+
+    @chart.apply_transaction Transaction.new(
+      date: jan_1_2000,
+      debit:  { amount: 1, account_id: :my_bank, credit_or_debit: :debit },
+      credit: { amount: 1, account_id: :job, credit_or_debit: :credit },
+    )
+    @chart.apply_transaction Transaction.new(
+      date: jan_1_2000,
+      debit:  { amount: 5, account_id: :checking, credit_or_debit: :debit },
+      credit: { amount: 5, account_id: :job, credit_or_debit: :credit },
+    )
+    @chart.apply_transaction Transaction.new(
+      date: jan_1_2000,
+      debit:  { amount: 12, account_id: :checking_1, credit_or_debit: :debit },
+      credit: { amount: 12, account_id: :job, credit_or_debit: :credit },
+    )
+
+    assert_equal 12, @chart.account_balance(:checking_1)
+    assert_equal 0,  @chart.account_balance(:checking_2)
+    assert_equal 18, @chart.account_balance(:job)
+    assert_equal 17, @chart.account_balance(:checking)
+    assert_equal 0,  @chart.account_balance(:savings)
+    assert_equal 18, @chart.account_balance(:my_bank)
+  end
+
+  private
+
+  def add_smattering_of_accounts
+    @chart.add_account :checking, type: :asset, opening_balance: 25
+    @chart.add_account :savings, type: :asset, opening_balance: 400
+    @chart.add_account :auto, type: :asset, opening_balance: 15000
+    @chart.add_account :bills, type: :expense, opening_balance: 26
+    @chart.add_account :car_loan, type: :liability, opening_balance: 13000
+    @chart.add_account :new_job, type: :revenue, opening_balance: 500
+  end
+end