fin_it 0.1.0

data/lib/fin_it/temporal_value.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require 'money'
+
+module FinIt
+  # Represents a value that can change over time with currency support
+  class TemporalValue
+    attr_reader :variable_name, :periods, :default_currency
+
+    def initialize(variable_name, default_currency: 'USD')
+      @variable_name = variable_name
+      @periods = []
+      @default_currency = default_currency
+      
+      # Configure Money gem
+      Money.locale_backend = nil
+      Money.rounding_mode = BigDecimal::ROUND_HALF_UP
+    end
+
+    # Add a time-bounded value with currency support
+    # @param value [Numeric, Money] The value
+    # @param start_date [Date, nil] When this value starts (nil = beginning of time)
+    # @param end_date [Date, nil] When this value ends (nil = forever)
+    # @param currency [String, nil] Currency code (nil for non-financial values like drivers)
+    def add_period(value, start_date: nil, end_date: nil, currency: nil, metadata: {})
+      currency ||= @default_currency unless currency == nil  # Allow explicit nil for drivers
+      
+      # Convert to Money object if currency is provided and not already Money
+      stored_value = if value.is_a?(Money)
+        value
+      elsif currency
+        # Money gem uses cents internally
+        Money.new((value * 100).to_i, currency)
+      else
+        # Non-financial value (driver) - store as-is
+        value
+      end
+      
+      @periods << {
+        value: stored_value,
+        start_date: parse_date(start_date),
+        end_date: parse_date(end_date),
+        metadata: metadata
+      }
+      
+      # Sort periods by start date
+      @periods.sort_by! { |p| p[:start_date] || Date.new(1900, 1, 1) }
+    end
+
+    # Get value for a specific date with optional currency conversion
+    # @param date [Date] The date to query
+    # @param output_currency [String, nil] Currency to convert to
+    # @param period_type [Symbol] The period type to calculate for (:annual, :monthly, :daily, :weekly)
+    # @return [Money, Numeric, nil] The value at that date
+    def value_at(date, output_currency: nil, period_type: :annual)
+      date = parse_date(date)
+      
+      period = @periods.find do |p|
+        start_ok = p[:start_date].nil? || p[:start_date] <= date
+        end_ok = p[:end_date].nil? || date <= p[:end_date]
+        start_ok && end_ok
+      end
+      
+      return nil unless period
+      
+      value = period[:value]
+      frequency = period[:metadata][:frequency] || :annual
+      is_driver = period[:metadata][:is_driver] || false
+      
+      # Driver variables are returned as-is (no scaling or currency conversion)
+      return value if is_driver
+      
+      # Scale value based on requested period type for financial variables
+      # The stored value is annualized, so we need to scale it down for shorter periods
+      # For annual frequency, when requesting monthly, only show in payment month
+      scaled_value = scale_value_for_period(value, frequency, period_type, period, date)
+      
+      # Convert if different currency requested
+      if output_currency && scaled_value.is_a?(Money) && output_currency != scaled_value.currency.iso_code
+        scaled_value.exchange_to(output_currency)
+      else
+        scaled_value
+      end
+    end
+
+    # Get all values in a date range
+    # @param start_date [Date] Start of range
+    # @param end_date [Date] End of range
+    # @return [Array<Hash>] Array of {date:, value:} hashes
+    def values_in_range(start_date, end_date, frequency: :monthly)
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+      
+      dates = generate_date_range(start_date, end_date, frequency)
+      
+      dates.map do |date|
+        {
+          date: date,
+          value: value_at(date),
+          period: find_period_info(date)
+        }
+      end
+    end
+
+    # Check if value changes in a given range
+    def changes_in_range?(start_date, end_date)
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+      
+      @periods.count do |p|
+        (p[:start_date] && p[:start_date].between?(start_date, end_date)) ||
+        (p[:end_date] && p[:end_date].between?(start_date, end_date))
+      end > 1
+    end
+
+    private
+
+    def scale_value_for_period(money_value, frequency, period_type, period = nil, date = nil)
+      # If not Money (e.g., a driver variable like employee count), return as-is
+      return money_value unless money_value.is_a?(Money)
+      
+      # If period_type matches frequency, return as-is (already annualized)
+      # Otherwise, scale based on the requested period
+      case period_type
+      when :annual
+        money_value # Already stored as annual
+      when :monthly
+        # For annual frequency, only show value in the payment month
+        # Default: show in the first month of the period's date range
+        if frequency == :annual
+          if period && period[:start_date] && date
+            # Check if this month contains the payment date
+            # For annual payments, default to showing in the month of start_date
+            payment_month = period[:start_date].month
+            payment_year = period[:start_date].year
+            if date.month == payment_month && date.year == payment_year
+              # This is the payment month - show full annual value
+              money_value
+            else
+              # Not the payment month - show zero
+              Money.new(0, money_value.currency)
+            end
+          else
+            # No date info - divide by 12 as fallback
+            Money.new((money_value.fractional / 12.0).round, money_value.currency)
+          end
+        else
+          # For non-annual frequencies, divide annual by 12
+          Money.new((money_value.fractional / 12.0).round, money_value.currency)
+        end
+      when :weekly
+        # Divide annual by 52
+        Money.new((money_value.fractional / 52.0).round, money_value.currency)
+      when :daily
+        # Divide annual by 365
+        Money.new((money_value.fractional / 365.0).round, money_value.currency)
+      when :quarterly
+        # For quarterly frequency, when requesting quarterly period_type, return quarterly amount (annual / 4)
+        # But if frequency is quarterly and we're asking for quarterly, we want the actual quarterly payment amount
+        if frequency == :quarterly
+          # Variable is quarterly frequency - return quarterly amount (annual / 4)
+          Money.new((money_value.fractional / 4.0).round, money_value.currency)
+        else
+          # Variable is annual frequency but requesting quarterly - return annual value (show full year in quarter)
+          money_value
+        end
+      else
+        money_value
+      end
+    end
+
+    def parse_date(date)
+      return nil if date.nil?
+      return date if date.is_a?(Date)
+      
+      case date
+      when String
+        if date =~ /^\d{4}-\d{2}$/ # YYYY-MM format
+          Date.parse("#{date}-01")
+        else
+          Date.parse(date)
+        end
+      when Time
+        date.to_date
+      else
+        raise ArgumentError, "Cannot parse date: #{date}"
+      end
+    end
+
+    def generate_date_range(start_date, end_date, frequency)
+      dates = []
+      current = start_date
+      
+      while current <= end_date
+        dates << current
+        
+        current = case frequency
+        when :daily
+          current + 1
+        when :weekly
+          current + 7
+        when :monthly
+          current >> 1 # Next month
+        when :quarterly
+          current >> 3
+        when :annual
+          current >> 12
+        else
+          current >> 1 # Default to monthly
+        end
+      end
+      
+      dates
+    end
+
+    def find_period_info(date)
+      period = @periods.find do |p|
+        start_ok = p[:start_date].nil? || p[:start_date] <= date
+        end_ok = p[:end_date].nil? || date <= p[:end_date]
+        start_ok && end_ok
+      end
+
+      return nil unless period
+
+      {
+        start_date: period[:start_date],
+        end_date: period[:end_date],
+        metadata: period[:metadata]
+      }
+    end
+
+    public
+
+    # Deep clone this temporal value
+    def deep_clone
+      cloned = TemporalValue.new(@variable_name, default_currency: @default_currency)
+      @periods.each do |period|
+        cloned_value = if period[:value].is_a?(Money)
+          Money.new(period[:value].fractional, period[:value].currency)
+        else
+          period[:value]
+        end
+        cloned.instance_variable_get(:@periods) << {
+          value: cloned_value,
+          start_date: period[:start_date],
+          end_date: period[:end_date],
+          metadata: period[:metadata].dup
+        }
+      end
+      cloned
+    end
+
+    # Set or replace a period with a new value
+    def set_period(value, start_date: nil, end_date: nil)
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+
+      # Find existing period that matches the date range
+      existing_idx = @periods.find_index do |p|
+        if start_date && end_date
+          p[:start_date] == start_date && p[:end_date] == end_date
+        elsif start_date
+          p[:start_date] == start_date
+        elsif end_date
+          p[:end_date] == end_date
+        else
+          p[:start_date].nil? && p[:end_date].nil?
+        end
+      end
+
+      if existing_idx
+        # Update existing period
+        period = @periods[existing_idx]
+        period[:value] = convert_value(value, period[:metadata])
+      else
+        # Add new period - get currency from first existing period or default
+        currency = @periods.any? ? @periods.first[:value]&.currency&.iso_code : @default_currency
+        metadata = @periods.any? ? @periods.first[:metadata].dup : {}
+        add_period(value, start_date: start_date, end_date: end_date,
+                   currency: metadata[:is_driver] ? nil : currency, metadata: metadata)
+      end
+    end
+
+    # Scale all periods by a factor within optional date range
+    def scale_periods(factor, start_date: nil, end_date: nil)
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+
+      @periods.each do |period|
+        # Check if period overlaps with the date range
+        next unless period_in_range?(period, start_date, end_date)
+
+        if period[:value].is_a?(Money)
+          period[:value] = Money.new((period[:value].fractional * factor).round, period[:value].currency)
+        elsif period[:value].is_a?(Numeric)
+          period[:value] = period[:value] * factor
+        end
+      end
+    end
+
+    # Adjust all periods by an amount within optional date range
+    def adjust_periods(amount, start_date: nil, end_date: nil)
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+
+      @periods.each do |period|
+        next unless period_in_range?(period, start_date, end_date)
+
+        if period[:value].is_a?(Money)
+          period[:value] = Money.new(period[:value].fractional + (amount * 100).to_i, period[:value].currency)
+        elsif period[:value].is_a?(Numeric)
+          period[:value] = period[:value] + amount
+        end
+      end
+    end
+
+    private
+
+    def period_in_range?(period, start_date, end_date)
+      return true if start_date.nil? && end_date.nil?
+
+      period_start = period[:start_date]
+      period_end = period[:end_date]
+
+      # Check if periods overlap
+      if start_date && end_date && period_start && period_end
+        period_end >= start_date && period_start <= end_date
+      elsif start_date && period_end
+        period_end >= start_date
+      elsif end_date && period_start
+        period_start <= end_date
+      else
+        true
+      end
+    end
+
+    def convert_value(value, metadata)
+      is_driver = metadata[:is_driver]
+      if value.is_a?(Money)
+        value
+      elsif !is_driver && @default_currency
+        Money.new((value * 100).to_i, @default_currency)
+      else
+        value
+      end
+    end
+  end
+end
+

data/lib/fin_it/transaction_generator/account_resolver.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative '../account'
+
+module FinIt
+  class TransactionGenerator
+    # Handles account determination for double-entry transactions
+    module AccountResolver
+      def determine_accounts(var_data, category)
+        # If explicit debit/credit accounts are specified, use them
+        if var_data[:debit_account] && var_data[:credit_account]
+          # Resolve account names (handle hierarchical accounts)
+          debit_account = resolve_account_name(var_data[:debit_account])
+          credit_account = resolve_account_name(var_data[:credit_account])
+          return [debit_account, credit_account] if debit_account && credit_account
+        end
+        
+        case category.type
+        when :income
+          # Income: Debit asset account (where money goes), Credit income P&L account
+          # With hierarchical accounts:
+          # - var_data[:pl_account] is the variable's auto-created income account (for P&L tracking, e.g., :salary)
+          # - var_data[:account] is the asset account where income goes (e.g., :checking)
+          # - var_data[:credit_account]/[:debit_account] are explicit overrides if specified
+          # - If no explicit account specified, use default asset account
+          asset_account = resolve_account_name(var_data[:credit_account] || var_data[:debit_account] || var_data[:account]) || find_default_asset_account
+          # P&L account for income tracking (auto-created, stored in var_data[:pl_account])
+          income_account = resolve_account_name(var_data[:pl_account] || var_data[:account])
+          # If variable account not found, fall back to equity (shouldn't happen with auto-creation)
+          income_account ||= find_equity_account
+          [asset_account, income_account]
+
+        when :expense
+          # Expense: Debit expense P&L account, Credit asset/liability account (where money comes from)
+          # With hierarchical accounts:
+          # - var_data[:pl_account] is the variable's auto-created expense account (for P&L tracking, e.g., :rent)
+          # - var_data[:account] is the asset account where money comes from (e.g., :checking)
+          # - var_data[:debit_account]/[:credit_account] are explicit overrides if specified
+          # - If no explicit account specified, use default asset account
+          # P&L account for expense tracking (auto-created, stored in var_data[:pl_account])
+          expense_account = resolve_account_name(var_data[:pl_account] || var_data[:account])
+          # If variable account not found, fall back to equity (shouldn't happen with auto-creation)
+          expense_account ||= find_equity_account
+          asset_account = resolve_account_name(var_data[:debit_account] || var_data[:credit_account] || var_data[:account]) || find_default_asset_account
+          [expense_account, asset_account]
+          
+        when :asset, :liability, :equity
+          # These are balance sheet accounts - typically don't generate transactions directly
+          # But if account is specified, we might need to handle transfers
+          account = var_data[:account] || var_data[:debit_account] || var_data[:credit_account]
+          return nil unless account
+          # For now, return nil - these will be handled differently
+          nil
+          
+        else
+          nil
+        end
+      end
+      
+      # Resolve account name, handling hierarchical accounts
+      def resolve_account_name(account_ref)
+        return nil unless account_ref
+        
+        account_name = account_ref.is_a?(Array) ? account_ref.last : account_ref
+        account_name = account_name.to_sym
+        
+        # Check if account exists
+        return account_name if @model.accounts.key?(account_name)
+        
+        # Try hierarchical path lookup if it's an array
+        if account_ref.is_a?(Array)
+          found_account = @model.find_account_by_path(account_ref.map(&:to_sym))
+          return found_account.name if found_account
+        end
+        
+        # Try to find by full name if it contains dots
+        if account_name.to_s.include?('.')
+          path_array = account_name.to_s.split('.').map(&:to_sym)
+          found_account = @model.find_account_by_path(path_array)
+          return found_account.name if found_account
+        end
+        
+        account_name
+      end
+      
+      def find_default_asset_account
+        # Find an asset account with opening balance (actual bank account) first,
+        # then fall back to any asset account, then create a default one
+        asset_accounts = @model.accounts.values.select { |acc| acc.type == :asset }
+
+        # Prefer accounts with opening balance (real accounts like checking/savings)
+        asset_account = asset_accounts.find { |acc| acc.opening_balance.to_f != 0 }
+        # Fall back to any asset account
+        asset_account ||= asset_accounts.first
+
+        unless asset_account
+          # Create default asset account
+          asset_account = Account.new(
+            :default_asset,
+            type: :asset,
+            currency: @model.config[:default_currency] || 'USD',
+            opening_balance: 0
+          )
+          @model.accounts[:default_asset] = asset_account
+        end
+
+        asset_account.name
+      end
+      
+      def find_equity_account
+        equity_account = @model.accounts.values.find { |acc| acc.type == :equity }
+        equity_account ? equity_account.name : :equity
+      end
+      
+    end
+  end
+end
+

data/lib/fin_it/transaction_generator/cache_management.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FinIt
+  class TransactionGenerator
+    # Handles transaction cache validation and invalidation
+    module CacheManagement
+      # Check if transaction cache is valid
+      def cache_valid?
+        current_hashes = @model.calculator.all_variable_hashes
+        
+        # Check if any variable hash has changed
+        current_hashes.each do |var_name, hash|
+          if @variable_hash_cache[var_name] != hash
+            return false
+          end
+        end
+        
+        # Check if any variable was removed
+        @variable_hash_cache.keys.each do |var_name|
+          unless current_hashes.key?(var_name)
+            return false
+          end
+        end
+        
+        true
+      end
+      
+      def invalidate_cache_if_needed
+        unless cache_valid?
+          @transactions.clear
+          @variable_hash_cache = @model.calculator.all_variable_hashes.dup
+          @max_generated_date = nil
+          @opening_balance_transactions_generated = false
+        end
+      end
+    end
+  end
+end
+

data/lib/fin_it/transaction_generator/date_generation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module FinIt
+  class TransactionGenerator
+    # Handles transaction date generation based on frequency and payment schedules
+    module DateGeneration
+      def generate_transaction_dates(start_date, end_date, frequency, payment_schedule)
+        dates = []
+        current = start_date
+        
+        if payment_schedule && payment_schedule.respond_to?(:payment_dates)
+          # Use payment schedule to determine dates
+          dates = payment_schedule.payment_dates(start_date, end_date)
+        else
+          # Generate dates based on frequency
+          while current <= end_date
+            dates << current
+            
+            current = case frequency
+            when :daily
+              current + 1
+            when :weekly
+              current + 7
+            when :monthly
+              current >> 1
+            when :quarterly
+              current >> 3
+            when :annual
+              current >> 12
+            else
+              current >> 1 # Default monthly
+            end
+          end
+        end
+        
+        dates
+      end
+      
+      def parse_date(date)
+        return date if date.is_a?(Date)
+        return nil if date.nil?
+        
+        case date
+        when String
+          Date.parse(date)
+        when Time
+          date.to_date
+        else
+          date
+        end
+      end
+    end
+  end
+end
+