fin_it 0.1.0

data/lib/fin_it/transaction_generator.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+# TransactionGenerator - Generates double-entry transactions for financial variables
+#
+# This class handles:
+# - Transaction generation from financial variables
+# - Double-entry accounting compliance
+# - Transaction querying and filtering
+#
+# Concerns extracted to modules:
+# - TransactionGenerator::AccountResolver - Determines debit/credit accounts
+# - TransactionGenerator::DateGeneration - Generates transaction dates from frequency/schedules
+# - TransactionGenerator::CacheManagement - Validates and invalidates transaction cache
+
+require 'date'
+require 'money'
+
+module FinIt
+  # Generates double-entry transactions for financial variables
+  class TransactionGenerator
+    # TransactionGenerator concerns - loaded explicitly to show dependencies
+    require_relative 'transaction_generator/account_resolver'
+    require_relative 'transaction_generator/date_generation'
+    require_relative 'transaction_generator/cache_management'
+    
+    include TransactionGenerator::AccountResolver
+    include TransactionGenerator::DateGeneration
+    include TransactionGenerator::CacheManagement
+    
+    attr_reader :model
+    
+    def initialize(model)
+      @model = model
+      @transactions = []
+      @variable_hash_cache = {}
+      @max_generated_date = nil
+      @opening_balance_transactions_generated = false
+    end
+    
+    # Generate all transactions up to end_date
+    def generate_transactions(end_date)
+      end_date = parse_date(end_date)
+      @model.validate_date!(end_date)
+      
+      # Clear existing transactions if variable hashes have changed
+      invalidate_cache_if_needed
+      
+      # If we've already generated transactions up to or beyond this date, skip
+      if @max_generated_date && end_date <= @max_generated_date && cache_valid?
+        return @transactions
+      end
+      
+      # Generate opening balance transactions first (on start_date)
+      generate_opening_balance_transactions
+      
+      # Generate transactions for all financial variables
+      @model.categories.each do |category|
+        generate_category_transactions(category, end_date)
+      end
+      
+      # Generate transactions for complex models
+      @model.complex_models.each do |name, complex_model|
+        generate_complex_model_transactions(complex_model, end_date)
+      end
+      
+      # Sort transactions by date
+      @transactions.sort_by! { |t| t[:date] }
+      
+      # Update max generated date
+      @max_generated_date = end_date if !@max_generated_date || end_date > @max_generated_date
+      
+      @transactions
+    end
+    
+    # Query transactions
+    def transactions(date_range: nil, account: nil, variable: nil)
+      result = @transactions.dup
+      
+      # Filter by date range
+      if date_range
+        start_date = parse_date(date_range[:start] || date_range[:start_date])
+        end_date = parse_date(date_range[:end] || date_range[:end_date])
+        
+        result.select! do |t|
+          t[:date] >= start_date && t[:date] <= end_date
+        end
+      end
+      
+      # Filter by account
+      if account
+        account_sym = account.is_a?(Symbol) ? account : account.to_sym
+        result.select! do |t|
+          t[:debit_account] == account_sym || t[:credit_account] == account_sym
+        end
+      end
+      
+      # Filter by variable
+      if variable
+        var_sym = variable.is_a?(Symbol) ? variable : variable.to_sym
+        result.select! { |t| t[:variable] == var_sym }
+      end
+      
+      result
+    end
+    
+    private
+    
+    def generate_opening_balance_transactions
+      # Only generate opening balance transactions once (on first call)
+      return if @opening_balance_transactions_generated
+      
+      @model.accounts.each do |account_name, account|
+        next if account.opening_balance.to_f == 0
+        next if account.type == :equity # Equity changes come from operations
+        
+        # Create opening balance transaction on model start_date
+        amount = Money.new((account.opening_balance.to_f * 100).to_i, account.currency)
+        amount_value = account.opening_balance.to_f
+        
+        # Determine debit and credit accounts based on account type
+        if account.type == :asset
+          # Asset opening balance: Debit asset, Credit equity/liability
+          debit_account = account_name
+          credit_account = ensure_account_exists_for_opening_balance(account.opening_balance_credit_account, amount_value)
+        elsif account.type == :liability
+          # Liability opening balance: Credit liability, Debit equity
+          debit_account = ensure_account_exists_for_opening_balance(account.opening_balance_credit_account, amount_value)
+          credit_account = account_name
+        else
+          next # Skip other types
+        end
+        
+        transaction = {
+          date: @model.start_date,
+          variable: :opening_balance,
+          amount: amount,
+          debit_account: debit_account,
+          credit_account: credit_account,
+          description: "Opening balance for #{account_name}",
+          currency: account.currency
+        }
+        
+        @transactions << transaction
+      end
+      
+      @opening_balance_transactions_generated = true
+    end
+    
+    def ensure_account_exists_for_opening_balance(account_ref, amount)
+      # Handle array notation for hierarchical accounts (e.g., [:equity, :safe_investment])
+      if account_ref.is_a?(Array)
+        return ensure_account_hierarchy_exists(account_ref, amount)
+      end
+
+      # Handle symbol notation (backward compatible)
+      account_name = account_ref.to_sym
+
+      # Check if account exists - if so, just return the name
+      # Do NOT modify existing account balances - the transactions will handle the double-entry
+      if @model.accounts.key?(account_name)
+        return account_name
+      end
+      
+      # Account doesn't exist - determine type and create with amount
+      account_type = if account_name.to_s.downcase.include?('liability') || account_name.to_s.downcase.include?('liab')
+        :liability
+      else
+        :equity
+      end
+      
+      # Create the account with accumulated balance
+      require_relative '../account'
+      new_account = Account.new(
+        account_name,
+        type: account_type,
+        currency: @model.config[:default_currency] || 'USD',
+        opening_balance: amount,
+        opening_balance_credit_account: :equity
+      )
+      
+      @model.accounts[account_name] = new_account
+      account_name
+    end
+    
+    def ensure_account_hierarchy_exists(path_array, amount)
+      # Ensure account hierarchy exists and accumulate balance to leaf account
+      path_array = path_array.map(&:to_sym)
+      return nil if path_array.empty?
+      
+      # Determine account type from first element
+      first_element = path_array.first.to_s.downcase
+      account_type = if first_element.include?('liability') || first_element.include?('liab')
+        :liability
+      elsif first_element == 'equity' || first_element.include?('equity')
+        :equity
+      elsif first_element.include?('asset')
+        :asset
+      else
+        :equity # Default
+      end
+      
+      # Check if hierarchy already exists - if so, just return the name
+      # Do NOT modify existing account balances - the transactions will handle the double-entry
+      existing_account = @model.find_account_by_path(path_array)
+      if existing_account
+        return existing_account.name
+      end
+      
+      # Create hierarchy - start with root account
+      require_relative '../account'
+      current_account = @model.accounts[path_array.first]
+      
+      if current_account.nil?
+        # Create root account with 0 balance (will accumulate later)
+        current_account = Account.new(
+          path_array.first,
+          type: account_type,
+          currency: @model.config[:default_currency] || 'USD',
+          opening_balance: 0,
+          opening_balance_credit_account: :equity
+        )
+        @model.accounts[path_array.first] = current_account
+      end
+      
+      # Traverse/create path for remaining elements
+      path_array[1..-1].each_with_index do |account_name, idx|
+        # Check if child account exists
+        child_account = current_account.children.find { |child| child.name == account_name }
+        
+        if child_account.nil?
+          # Create child account
+          is_leaf = (idx == path_array.length - 2) # Last element in remaining path
+          child_account = Account.new(
+            account_name,
+            type: account_type,
+            currency: @model.config[:default_currency] || 'USD',
+            opening_balance: is_leaf ? amount : 0, # Only leaf gets the amount
+            opening_balance_credit_account: :equity,
+            parent: current_account
+          )
+          @model.accounts[account_name] = child_account
+          current_account.children << child_account
+        end
+        # Note: We no longer accumulate balance to existing leaf accounts
+        # The transactions will handle the double-entry accounting
+        
+        current_account = child_account
+      end
+      
+      # Return leaf account name
+      path_array.last
+    end
+    
+    def generate_category_transactions(category, end_date)
+      # Process variables in this category
+      category.variables.each do |var_data|
+        generate_variable_transactions(var_data, category, end_date)
+      end
+      
+      # Process subcategories recursively
+      category.children.each do |child|
+        generate_category_transactions(child, end_date)
+      end
+    end
+    
+    def generate_variable_transactions(var_data, category, end_date)
+      var_name = var_data[:name]
+      
+      # Skip driver variables (non-financial)
+      return if category.type == :driver
+      
+      # Skip if variable doesn't have account mappings
+      # For income/expense, we can use default asset account if none specified
+      if [:income, :expense].include?(category.type)
+        # Income/expense requires either pl_account or explicit accounts
+        # pl_account is auto-created for all income/expense variables
+        unless var_data[:pl_account] || var_data[:account] || var_data[:debit_account] || var_data[:credit_account]
+          return
+        end
+      else
+        # For asset/liability/equity, skip if no account specified
+        return unless var_data[:account] || var_data[:debit_account] || var_data[:credit_account]
+      end
+      
+      # Determine accounts based on category type
+      debit_account, credit_account = determine_accounts(var_data, category)
+      
+      return unless debit_account && credit_account
+      
+      # Get variable frequency and dates
+      frequency = var_data[:frequency] || :annual
+      start_date = parse_date(var_data[:start_date]) || @model.start_date
+      var_end_date = parse_date(var_data[:end_date]) || end_date
+      
+      # Generate transaction dates based on frequency
+      transaction_dates = generate_transaction_dates(start_date, [var_end_date, end_date].min, frequency, var_data[:payment_schedule])
+      
+      transaction_dates.each do |date|
+        # Calculate variable value for this date
+        value = @model.calculator.calculate(
+          var_name,
+          date: date,
+          period_type: frequency == :annual ? :annual : frequency
+        )
+        
+        next unless value
+        
+        # Store amount as Money object for precision and currency safety
+        # Convert to Money if not already (from calculator, it should be Money)
+        amount = if value.is_a?(Money)
+          value
+        else
+          Money.new((value.to_f * 100).to_i, @model.config[:default_currency])
+        end
+        
+        # Create transaction
+        transaction = {
+          date: date,
+          variable: var_name,
+          amount: amount,  # Money object
+          debit_account: debit_account,
+          credit_account: credit_account,
+          description: var_data[:description] || "Transaction for #{var_name}",
+          currency: amount.currency.iso_code
+        }
+        
+        @transactions << transaction
+      end
+    end
+    
+    def generate_complex_model_transactions(complex_model, end_date)
+      # Build model context with calculator values
+      # Keep Money objects for precision, convert to float only if needed by model
+      model_context = {}
+      @model.calculator.variable_names.each do |var_name|
+        # Get value at model start date for context
+        value = @model.calculator.calculate(var_name, date: complex_model.start_date)
+        if value
+          # Pass Money objects to complex models for precision
+          # Models can convert to float if needed, but we preserve Money when possible
+          model_context[var_name] = value
+        end
+      end
+      
+      # Calculate transactions from complex model
+      model_transactions = complex_model.calculate_transactions(
+        end_date,
+        @model.calculator,
+        model_context
+      )
+      
+      @transactions.concat(model_transactions)
+    end
+    
+  end
+end
+

data/lib/fin_it/version.rb

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

data/lib/fin_it.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "money"
+require "bigdecimal"
+
+# Set Money rounding mode to avoid warnings
+Money.rounding_mode = BigDecimal::ROUND_HALF_UP
+
+require "fin_it/version"
+require "fin_it/engine"
+require "fin_it/account"
+require "fin_it/temporal_value"
+require "fin_it/calculator"
+require "fin_it/plan"
+require "fin_it/dsl"
+require "fin_it/categories/category"
+
+# Require reports
+Dir[File.join(__dir__, 'fin_it/reports/*.rb')].each { |file| require file }
+
+# Require outputs
+Dir[File.join(__dir__, 'fin_it/outputs/*.rb')].each { |file| require file }
+
+module FinIt
+  class Error < StandardError; end
+end
+

data/test/fin_it/calculator_test.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class CalculatorTest < Minitest::Test
+  def setup
+    @model = FinIt.define(default_currency: 'USD') do
+      config do
+        start_date 2024
+      end
+      
+      account :checking do
+        type :asset
+        currency 'USD'
+        opening_balance 10_000
+      end
+      
+      account :savings do
+        type :asset
+        currency 'USD'
+        opening_balance 50_000
+      end
+      
+      category :income, type: :income do
+        # Bonus that switches accounts mid-year
+        variable :q1_bonus, currency: 'USD', frequency: :annual, account: :checking do
+          value 25_000, start_date: "2024-01-01", end_date: "2024-03-31"
+          value 0, start_date: "2024-04-01", end_date: "2024-12-31"
+          description "Q1 bonus to checking"
+        end
+        
+        variable :q4_bonus, currency: 'USD', frequency: :annual, account: :savings do
+          value 0, start_date: "2024-01-01", end_date: "2024-09-30"
+          value 50_000, start_date: "2024-10-01", end_date: "2024-12-31"
+          description "Q4 bonus to savings"
+        end
+      end
+    end
+  end
+  
+  def test_q1_bonus_in_february
+    q1_value = @model.calculator.calculate(:q1_bonus, date: Date.new(2024, 2, 15), period_type: :annual).to_f
+    assert_in_delta 25_000, q1_value, 0.01, "Q1 bonus should be $25,000 in February"
+  end
+  
+  def test_q1_bonus_in_may
+    q2_value = @model.calculator.calculate(:q1_bonus, date: Date.new(2024, 5, 15), period_type: :annual).to_f
+    assert_equal 0, q2_value, "Q1 bonus should be $0 in May"
+  end
+  
+  def test_q4_bonus_in_november
+    q4_bonus = @model.calculator.calculate(:q4_bonus, date: Date.new(2024, 11, 15), period_type: :annual).to_f
+    assert_in_delta 50_000, q4_bonus, 0.01, "Q4 bonus should be $50,000 in November"
+  end
+  
+  def test_expense_paid_on_specific_date
+    expense_model = FinIt.define(default_currency: 'USD') do
+      config do
+        start_date 2024
+      end
+      
+      account :credit_card do
+        type :liability
+        currency 'USD'
+      end
+      
+      category :expenses, type: :expense do
+        # Monthly rent paid on the 1st of each month
+        variable :rent, currency: 'USD', frequency: :monthly, account: :credit_card do
+          value 2_000, start_date: "2024-01-01", end_date: "2024-12-31"
+          description "Monthly rent"
+        end
+        
+        # Quarterly insurance paid on specific dates
+        calculated :insurance,
+          formula: "5000",
+          frequency: :quarterly,
+          payment_schedule: { months: [1, 4, 7, 10], day: 1 },
+          start_date: "2024-01-01",
+          end_date: "2024-12-31",
+          account: :credit_card do
+          description "Quarterly insurance premium"
+        end
+      end
+    end
+    
+    # Rent should be available on any date within the period (it's a variable, not calculated with payment schedule)
+    rent_feb_1 = expense_model.calculator.calculate(:rent, date: Date.new(2024, 2, 1), period_type: :monthly)
+    assert rent_feb_1, "Rent should exist on Feb 1"
+    assert_in_delta 2_000, rent_feb_1.to_f, 0.01, "Rent should be $2,000/month"
+    
+    # Insurance should only be paid on quarterly payment dates (Jan 1, Apr 1, Jul 1, Oct 1)
+    insurance_jan_1 = expense_model.calculator.calculate(:insurance, date: Date.new(2024, 1, 1), output_currency: 'USD')
+    assert insurance_jan_1, "Insurance should be paid on Jan 1 (payment date)"
+    assert_in_delta 5_000, insurance_jan_1.to_f, 0.01, "Insurance should be $5,000 on payment date"
+    
+    insurance_apr_1 = expense_model.calculator.calculate(:insurance, date: Date.new(2024, 4, 1), output_currency: 'USD')
+    assert insurance_apr_1, "Insurance should be paid on Apr 1 (payment date)"
+    assert_in_delta 5_000, insurance_apr_1.to_f, 0.01, "Insurance should be $5,000 on payment date"
+    
+    # Insurance should NOT be paid on non-payment dates
+    insurance_feb_15 = expense_model.calculator.calculate(:insurance, date: Date.new(2024, 2, 15), output_currency: 'USD')
+    assert_nil insurance_feb_15, "Insurance should be nil on Feb 15 (not a payment date)"
+    
+    insurance_may_15 = expense_model.calculator.calculate(:insurance, date: Date.new(2024, 5, 15), output_currency: 'USD')
+    assert_nil insurance_may_15, "Insurance should be nil on May 15 (not a payment date)"
+  end
+end
+

data/test/fin_it/complex_model_test.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class ComplexModelTest < Minitest::Test
+  def setup
+    @model = FinIt.define(default_currency: 'USD') do
+      config do
+        start_date 2024
+      end
+      
+      account :mortgage do
+        type :liability
+        currency 'USD'
+        opening_balance 300_000  # Positive value
+      end
+      
+      account :checking do
+        type :asset
+        currency 'USD'
+        opening_balance 350_000  # 50k initial + 300k borrowed = 350k
+      end
+      
+      # Define reusable mortgage payment template
+      define_model :mortgage_payment do
+        variable :principal
+        variable :rate
+        variable :term_years
+        
+        default_debit_accounts [:mortgage, :equity]
+        default_credit_accounts [:checking]
+        
+        calculation do |date, context|
+          # Simple amortization calculation
+          principal_balance = context[:principal] || 300_000
+          monthly_rate = (context[:rate] || 0.04) / 12.0
+          total_payments = (context[:term_years] || 30) * 12
+          
+          # Calculate monthly payment
+          if principal_balance > 0
+            monthly_payment = principal_balance * (monthly_rate * (1 + monthly_rate)**total_payments) / 
+                              ((1 + monthly_rate)**total_payments - 1)
+            
+            interest = principal_balance * monthly_rate
+            principal_portion = monthly_payment - interest
+            
+            # Return multiple transactions: principal + interest
+            [
+              {
+                amount: principal_portion,
+                debit_account: :mortgage,
+                credit_account: :checking,
+                description: "Mortgage principal payment"
+              },
+              {
+                amount: interest,
+                debit_account: :equity,
+                credit_account: :checking,
+                description: "Mortgage interest expense"
+              }
+            ]
+          else
+            []
+          end
+        end
+      end
+      
+      # Instantiate mortgage with parameters
+      mortgage_payment do
+        start_date "2024-01-01"
+        end_date "2054-01-01"
+        frequency :monthly
+        principal 300_000
+        rate 0.04
+        term_years 30
+        debit_account :mortgage
+        credit_account :checking
+      end
+    end
+  end
+  
+  def test_template_exists
+    # Templates are stored in the builder, but we can't access them easily
+    # So we test through the model
+    assert @model.complex_models.any?, "Should have complex models"
+  end
+  
+  def test_mortgage_generates_transactions
+    # Generate transactions for first 3 months
+    transactions = @model.generate_transactions(Date.new(2024, 3, 31))
+    
+    # Should have mortgage transactions (principal + interest per month = 6 transactions)
+    mortgage_txns = transactions.select { |t| t[:variable].to_s.start_with?('mortgage_payment') }
+    assert mortgage_txns.any?, "Should have mortgage transactions"
+    
+    # Should have both principal and interest transactions
+    principal_txns = mortgage_txns.select { |t| t[:debit_account] == :mortgage }
+    interest_txns = mortgage_txns.select { |t| t[:debit_account] == :equity }
+    
+    assert principal_txns.any?, "Should have principal transactions"
+    assert interest_txns.any?, "Should have interest transactions"
+  end
+  
+  def test_multiple_transactions_per_period
+    transactions = @model.generate_transactions(Date.new(2024, 1, 31))
+    
+    # Get transactions for January 1st
+    jan_txns = transactions.select { |t| t[:date] == Date.new(2024, 1, 1) }
+    mortgage_jan = jan_txns.select { |t| t[:variable].to_s.start_with?('mortgage_payment') }
+    
+    # Should have 2 transactions (principal + interest) for the same date
+    assert mortgage_jan.length >= 2, "Should have multiple transactions per period"
+    
+    # Verify they have different accounts
+    accounts = mortgage_jan.map { |t| t[:debit_account] }.uniq
+    assert accounts.length >= 2, "Transactions should affect different accounts"
+  end
+  
+  def test_double_entry_compliance
+    transactions = @model.generate_transactions(Date.new(2024, 3, 31))
+    mortgage_txns = transactions.select { |t| t[:variable].to_s.start_with?('mortgage_payment') }
+    
+    # Verify double-entry: each transaction has debit and credit
+    mortgage_txns.each do |transaction|
+      assert transaction[:debit_account], "Transaction should have debit account"
+      assert transaction[:credit_account], "Transaction should have credit account"
+      assert transaction[:debit_account] != transaction[:credit_account], 
+        "Debit and credit accounts should differ"
+    end
+  end
+  
+  def test_reusable_template
+    # Create a second model using the same template with different parameters
+    model2 = FinIt.define(default_currency: 'USD') do
+      config do
+        start_date 2024
+      end
+      
+      account :mortgage_2 do
+        type :liability
+        currency 'USD'
+        opening_balance 200_000  # Positive value
+      end
+      
+      account :checking_2 do
+        type :asset
+        currency 'USD'
+        opening_balance 230_000  # 30k initial + 200k borrowed = 230k
+      end
+      
+      # Same template definition
+      define_model :mortgage_payment do
+        variable :principal
+        variable :rate
+        variable :term_years
+        
+        default_debit_accounts [:mortgage, :equity]
+        default_credit_accounts [:checking]
+        
+        calculation do |date, context|
+          principal_balance = context[:principal] || 200_000
+          monthly_rate = (context[:rate] || 0.035) / 12.0
+          total_payments = (context[:term_years] || 15) * 12
+          
+          if principal_balance > 0
+            monthly_payment = principal_balance * (monthly_rate * (1 + monthly_rate)**total_payments) / 
+                              ((1 + monthly_rate)**total_payments - 1)
+            interest = principal_balance * monthly_rate
+            principal_portion = monthly_payment - interest
+            
+            [
+              { amount: principal_portion, debit_account: :mortgage_2, credit_account: :checking_2 },
+              { amount: interest, debit_account: :equity, credit_account: :checking_2 }
+            ]
+          else
+            []
+          end
+        end
+      end
+      
+      # Different parameters
+      mortgage_payment do
+        start_date "2024-06-01"
+        principal 200_000
+        rate 0.035
+        term_years 15
+        debit_account :mortgage_2
+        credit_account :checking_2
+      end
+    end
+    
+    transactions = model2.generate_transactions(Date.new(2024, 6, 30))
+    mortgage_txns = transactions.select { |t| t[:variable].to_s.start_with?('mortgage_payment') }
+    
+    assert mortgage_txns.any?, "Second model should generate transactions"
+    assert mortgage_txns.first[:debit_account] == :mortgage_2, "Should use specified accounts"
+  end
+end