fin_it 0.1.0

data/lib/fin_it/financial_model/date_helpers.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module FinIt
+  class FinancialModel
+    # Date parsing, validation, and period type determination
+    module DateHelpers
+      # Validate that a date is >= start_date
+      def validate_date!(date)
+        date = parse_date(date)
+        if date < @start_date
+          raise StartDateValidationError.new(
+            "Date #{date} is before model start_date #{@start_date}. " \
+            "All transactions must occur on or after the model start_date."
+          )
+        end
+        date
+      end
+      
+      # Determine period type based on date range
+      def determine_period_type(start_date, end_date)
+        return :annual unless start_date && end_date
+        
+        start_date = parse_date(start_date)
+        end_date = parse_date(end_date)
+        
+        days = (end_date - start_date).to_i
+        if days <= 1
+          :daily
+        elsif days <= 7
+          :weekly
+        elsif days <= 35
+          :monthly
+        elsif days <= 100
+          :quarterly
+        else
+          :annual
+        end
+      end
+      
+      private
+      
+      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
+

data/lib/fin_it/financial_model/debugging.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+module FinIt
+  class FinancialModel
+    # Debugging and inspection methods for financial models
+    module Debugging
+      # Debugging: Print transactions for an account within a date range
+      def print_account_transactions(account_name, start_date: nil, end_date: nil, io: $stdout)
+        account = @accounts[account_name]
+        unless account
+          io.puts "Account '#{account_name}' not found"
+          return
+        end
+        
+        start_date ||= @start_date
+        end_date ||= Date.today
+        start_date = parse_date(start_date)
+        end_date = parse_date(end_date)
+        
+        # Generate transactions up to end_date
+        generate_transactions(end_date)
+        
+        # Get transactions for this account
+        account_txns = transactions(
+          date_range: { start: start_date, end: end_date },
+          account: account_name
+        )
+        
+        io.puts "=" * 100
+        io.puts "TRANSACTIONS FOR ACCOUNT: #{account_name.to_s.upcase}"
+        io.puts "Account Type: #{account.type.to_s.upcase} | Currency: #{account.currency}"
+        io.puts "Period: #{start_date} to #{end_date}"
+        io.puts "Opening Balance: #{format_currency(account.opening_balance.to_f, account.currency)}"
+        io.puts "=" * 100
+        
+        if account_txns.empty?
+          io.puts "No transactions found for this period."
+          return
+        end
+        
+        # Group by date
+        txns_by_date = account_txns.group_by { |t| t[:date] }
+        
+        # Use Money objects for precision
+        running_balance = Money.new((account.opening_balance.to_f * 100).to_i, account.currency)
+        
+        io.puts "%-12s %-20s %-30s %15s %15s %15s" % [
+          "Date", "Variable", "Description", "Debit", "Credit", "Balance"
+        ]
+        io.puts "-" * 100
+        
+        txns_by_date.sort.each do |date, txns|
+          txns.each do |txn|
+            # Convert transaction amount to Money if needed
+            txn_amount = txn[:amount]
+            if txn_amount.is_a?(Money)
+              if txn_amount.currency.iso_code != account.currency
+                txn_amount = txn_amount.exchange_to(account.currency)
+              end
+            else
+              txn_amount = Money.new((txn_amount.to_f * 100).to_i, account.currency)
+            end
+            
+            debit_amount = txn[:debit_account] == account_name ? txn_amount : Money.new(0, account.currency)
+            credit_amount = txn[:credit_account] == account_name ? txn_amount : Money.new(0, account.currency)
+            
+            if account.type == :asset
+              if debit_amount.zero? == false
+                running_balance += debit_amount
+              elsif credit_amount.zero? == false
+                running_balance -= credit_amount
+              end
+            else  # liability or equity
+              if debit_amount.zero? == false
+                running_balance -= debit_amount
+              elsif credit_amount.zero? == false
+                running_balance += credit_amount
+              end
+            end
+            
+            # Convert to float for display
+            debit_display = debit_amount.zero? ? 0 : debit_amount.to_f
+            credit_display = credit_amount.zero? ? 0 : credit_amount.to_f
+            
+            description = txn[:description] || "#{txn[:variable]} (#{txn[:debit_account]} -> #{txn[:credit_account]})"
+            
+            io.puts "%-12s %-20s %-30s %15s %15s %15s" % [
+              date.strftime("%Y-%m-%d"),
+              txn[:variable].to_s,
+              description[0..29],
+              debit_display > 0 ? format_currency(debit_display, account.currency) : "",
+              credit_display > 0 ? format_currency(credit_display, account.currency) : "",
+              format_currency(running_balance.to_f, account.currency)
+            ]
+          end
+        end
+        
+        io.puts "-" * 100
+        io.puts "%-62s %15s" % ["Ending Balance (#{end_date}):", format_currency(running_balance.to_f, account.currency)]
+        io.puts "=" * 100
+      end
+      
+      # Debugging: Print all accounts with balances as of a date, including variable info and hashes
+      def print_accounts_summary(as_of_date: nil, include_hashes: true, io: $stdout)
+        as_of_date ||= Date.today
+        as_of_date = parse_date(as_of_date)
+        validate_date!(as_of_date)
+        
+        # Generate transactions up to as_of_date
+        generate_transactions(as_of_date)
+        
+        io.puts "=" * 120
+        io.puts "ACCOUNT SUMMARY"
+        io.puts "As of: #{as_of_date}"
+        io.puts "=" * 120
+        
+        # Group accounts by type
+        accounts_by_type = @accounts.values.group_by(&:type)
+        
+        [:asset, :liability, :equity].each do |type|
+          accounts = accounts_by_type[type] || []
+          next if accounts.empty?
+          
+          io.puts "\n#{type.to_s.upcase}S"
+          io.puts "-" * 120
+          io.puts "%-30s %-10s %20s %20s %20s" % [
+            "Account Name", "Currency", "Opening Balance", "Current Balance", "Change"
+          ]
+          io.puts "-" * 120
+          
+          accounts.each do |account|
+            opening = account.opening_balance.to_f
+            current = account_balance(account.name, as_of_date: as_of_date)
+            change = current - opening
+            
+            io.puts "%-30s %-10s %20s %20s %20s" % [
+              account.name.to_s,
+              account.currency,
+              format_currency(opening, account.currency),
+              format_currency(current, account.currency),
+              format_currency(change, account.currency)
+            ]
+          end
+          
+          # Type subtotal
+          total_opening = accounts.sum { |a| a.opening_balance.to_f }
+          total_current = accounts.sum { |a| account_balance(a.name, as_of_date: as_of_date) }
+          total_change = total_current - total_opening
+          
+          io.puts "-" * 120
+          io.puts "%-30s %-10s %20s %20s %20s" % [
+            "Total #{type.to_s.capitalize}",
+            "",
+            format_currency(total_opening, @config[:default_currency]),
+            format_currency(total_current, @config[:default_currency]),
+            format_currency(total_change, @config[:default_currency])
+          ]
+        end
+        
+        # Balance sheet validation
+        total_assets = accounts_by_type[:asset]&.sum { |a| account_balance(a.name, as_of_date: as_of_date) } || 0
+        total_liabilities = accounts_by_type[:liability]&.sum { |a| account_balance(a.name, as_of_date: as_of_date) } || 0
+        total_equity = accounts_by_type[:equity]&.sum { |a| account_balance(a.name, as_of_date: as_of_date) } || 0
+        
+        io.puts "\n" + "=" * 120
+        io.puts "BALANCE SHEET VALIDATION"
+        io.puts "-" * 120
+        io.puts "Assets:      #{format_currency(total_assets, @config[:default_currency])}"
+        io.puts "Liabilities: #{format_currency(total_liabilities, @config[:default_currency])}"
+        io.puts "Equity:      #{format_currency(total_equity, @config[:default_currency])}"
+        io.puts "-" * 120
+        difference = (total_assets - (total_liabilities + total_equity)).abs
+        io.puts "Difference:  #{format_currency(difference, @config[:default_currency])}"
+        if difference <= 0.01
+          io.puts "✓ Balance sheet balances correctly"
+        else
+          io.puts "✗ Balance sheet does NOT balance!"
+        end
+        
+        # Variable information and hashes
+        if include_hashes
+          io.puts "\n" + "=" * 120
+          io.puts "VARIABLE INFORMATION & HASHES"
+          io.puts "-" * 120
+          
+          all_hashes = @calculator.all_variable_hashes
+          
+          # Group variables by category
+          @categories.each do |category|
+            next if category.type == :driver && category.variables.empty?
+            
+            io.puts "\n#{category.name.to_s.upcase} (#{category.type.to_s.upcase})"
+            io.puts "-" * 120
+            
+            category.all_variables.each do |var_data|
+              var_name = var_data[:name]
+              var_hash = all_hashes[var_name]
+              
+              # Get current value
+              current_value = begin
+                @calculator.calculate(var_name, date: as_of_date)
+              rescue => e
+                "Error: #{e.message}"
+              end
+              
+              value_str = if current_value.is_a?(Money)
+                format_currency(current_value.to_f, current_value.currency.iso_code)
+              elsif current_value.is_a?(Numeric)
+                format_number(current_value)
+              else
+                current_value.to_s
+              end
+              
+              io.puts "  Variable: #{var_name}"
+              io.puts "    Type: #{var_data[:type]}"
+              io.puts "    Value (#{as_of_date}): #{value_str}"
+              io.puts "    Hash: #{var_hash}"
+              
+              if var_data[:account]
+                io.puts "    Account: #{var_data[:account]}"
+              end
+              if var_data[:debit_account] || var_data[:credit_account]
+                io.puts "    Debit Account: #{var_data[:debit_account]}" if var_data[:debit_account]
+                io.puts "    Credit Account: #{var_data[:credit_account]}" if var_data[:credit_account]
+              end
+              if var_data[:frequency]
+                io.puts "    Frequency: #{var_data[:frequency]}"
+              end
+              if var_data[:formula]
+                io.puts "    Formula: #{var_data[:formula]}"
+              end
+              io.puts ""
+            end
+          end
+          
+          # Complex models
+          if @complex_models.any?
+            io.puts "\nCOMPLEX MODELS"
+            io.puts "-" * 120
+            @complex_models.each do |name, model|
+              model_hash = @calculator.complex_model_hash(model)
+              io.puts "  Model: #{name}"
+              io.puts "    Start Date: #{model.start_date}"
+              io.puts "    End Date: #{model.end_date || 'N/A'}"
+              io.puts "    Frequency: #{model.frequency}"
+              io.puts "    Hash: #{model_hash}"
+              io.puts ""
+            end
+          end
+        end
+        
+        io.puts "=" * 120
+      end
+      
+      # Debugging: Print variable values and hashes
+      def print_variables_summary(as_of_date: nil, io: $stdout)
+        as_of_date ||= Date.today
+        as_of_date = parse_date(as_of_date)
+        
+        io.puts "=" * 100
+        io.puts "VARIABLE VALUES & HASHES"
+        io.puts "As of: #{as_of_date}"
+        io.puts "=" * 100
+        
+        all_hashes = @calculator.all_variable_hashes
+        
+        io.puts "%-30s %-15s %-20s %30s" % [
+          "Variable Name", "Type", "Value", "Hash"
+        ]
+        io.puts "-" * 100
+        
+        @calculator.variable_names.sort.each do |var_name|
+          var_hash = all_hashes[var_name]
+          
+          value = begin
+            @calculator.calculate(var_name, date: as_of_date)
+          rescue => e
+            "Error: #{e.message[0..19]}"
+          end
+          
+          value_str = if value.is_a?(Money)
+            format_currency(value.to_f, value.currency.iso_code)
+          elsif value.is_a?(Numeric)
+            format_number(value)
+          else
+            value.to_s[0..19]
+          end
+          
+          var_type = @calculator.variables[var_name.to_sym]
+          type_str = if var_type.is_a?(Hash)
+            var_type[:type] || "unknown"
+          else
+            "temporal"
+          end
+          
+          io.puts "%-30s %-15s %-20s %30s" % [
+            var_name.to_s,
+            type_str.to_s,
+            value_str,
+            var_hash.to_s[0..29]
+          ]
+        end
+        
+        io.puts "=" * 100
+      end
+      
+      private
+      
+      def format_currency(value, currency = nil)
+        currency ||= @config[:default_currency] || 'USD'
+        
+        # Format number with commas and 2 decimal places
+        formatted = if value.is_a?(Money)
+          sprintf("%.2f", value.to_f)
+        else
+          sprintf("%.2f", value.to_f)
+        end
+        
+        # Add commas for thousands
+        formatted = formatted.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+        
+        # Add currency symbol
+        symbol = case currency.to_s.upcase
+        when 'USD' then '$'
+        when 'EUR' then '€'
+        when 'GBP' then '£'
+        when 'JPY' then '¥'
+        when 'MXN' then 'MXN$'
+        else "#{currency} "
+        end
+        
+        "#{symbol}#{formatted}"
+      end
+      
+      def format_number(value)
+        if value.is_a?(Money)
+          sprintf("%.2f", value.to_f)
+        elsif value.is_a?(Numeric)
+          if value.abs >= 1000
+            sprintf("%.2f", value)
+          elsif value.abs >= 1
+            sprintf("%.2f", value)
+          else
+            sprintf("%.4f", value)
+          end
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end
+

data/lib/fin_it/financial_model/period_flows.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'money'
+
+module FinIt
+  class FinancialModel
+    # Period flow calculations (flows during a period, not cumulative)
+    module PeriodFlows
+      # Calculate net flow for an account in a period (for income statements)
+      # Returns net flow from the account's perspective:
+      # - For equity: credits (income) are positive, debits (expenses) are negative
+      # - For assets: debits (money in) are positive, credits (money out) are negative
+      # - For liabilities: debits (payments) are negative, credits (borrowing) are positive
+      # Note: Account balances are always positive, but flows can be positive or negative
+      # @param variable [Symbol, nil] Optional variable name to filter transactions by specific variable
+      def account_period_flow(account_name, start_date, end_date, variable: nil)
+        account = @accounts[account_name]
+        return 0 unless account
+        
+        start_date = parse_date(start_date)
+        end_date = parse_date(end_date)
+        validate_date!(start_date)
+        validate_date!(end_date)
+        
+        # Generate transactions up to end_date if not already generated
+        @transaction_generator.generate_transactions(end_date)
+        
+        # Get all transactions affecting this account in the period
+        # Filter by variable if specified (for income/expense variable-specific flows)
+        account_transactions = @transaction_generator.transactions(
+          date_range: { start: start_date, end: end_date },
+          account: account_name,
+          variable: variable
+        )
+        
+        # Calculate net flow based on account type using Money objects for precision
+        # For income statements, we want:
+        # - Equity: credits (income) positive, debits (expenses) negative
+        # - Assets: debits (money in) positive, credits (money out) negative  
+        # - Liabilities: credits (borrowing) positive, debits (payments) negative
+        net_flow = Money.new(0, @config[:default_currency])
+        
+        account_transactions.each do |transaction|
+          # Convert transaction amount to account currency if needed
+          transaction_amount = transaction[:amount]
+          if transaction_amount.is_a?(Money)
+            # Convert to account currency if different
+            if transaction_amount.currency.iso_code != account.currency
+              transaction_amount = transaction_amount.exchange_to(account.currency)
+            end
+            # Convert to default currency for accumulation
+            if transaction_amount.currency.iso_code != @config[:default_currency]
+              transaction_amount = transaction_amount.exchange_to(@config[:default_currency])
+            end
+          else
+            # Legacy: convert float to Money (shouldn't happen after refactoring)
+            transaction_amount = Money.new((transaction_amount.to_f * 100).to_i, @config[:default_currency])
+          end
+          
+          if transaction[:debit_account] == account_name
+            # Debit to this account
+            if account.type == :equity
+              net_flow -= transaction_amount  # Debit to equity = expense (negative)
+            elsif account.type == :asset
+              net_flow += transaction_amount  # Debit to asset = money in (positive)
+            else  # liability
+              net_flow -= transaction_amount  # Debit to liability = payment (negative)
+            end
+          elsif transaction[:credit_account] == account_name
+            # Credit to this account
+            if account.type == :equity
+              net_flow += transaction_amount  # Credit to equity = income (positive)
+            elsif account.type == :asset
+              net_flow -= transaction_amount  # Credit to asset = money out (negative)
+            else  # liability
+              net_flow += transaction_amount  # Credit to liability = borrowing (positive)
+            end
+          end
+        end
+        
+        # Convert to account currency if needed
+        if account.currency != @config[:default_currency]
+          net_flow = net_flow.exchange_to(account.currency)
+        end
+        
+        # Return as float for backward compatibility
+        net_flow.to_f
+      end
+      
+      # Sum period flows for multiple accounts (for income statements)
+      def accounts_total_flow(account_names, start_date, end_date, output_currency: nil)
+        output_currency ||= @config[:default_currency]
+        start_date = parse_date(start_date)
+        end_date = parse_date(end_date)
+        validate_date!(start_date)
+        validate_date!(end_date)
+        
+        total = Money.new(0, output_currency)
+        
+        Array(account_names).each do |account_name|
+          account = @accounts[account_name]
+          next unless account
+          
+          # Use account period flow
+          flow = account_period_flow(account_name, start_date, end_date)
+          account_money = Money.new((flow * 100).to_i, account.currency)
+          
+          # Convert to output currency if needed
+          if account_money.currency.iso_code != output_currency
+            account_money = account_money.exchange_to(output_currency)
+          end
+          
+          total += account_money
+        end
+        
+        total.to_f
+      end
+    end
+  end
+end
+

data/lib/fin_it/financial_model/validation.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module FinIt
+  class FinancialModel
+    # Model validation logic
+    module Validation
+      # Validate the model
+      def validate!
+        validate_start_date!
+        validate_formula_dependencies!
+        validate_balance_sheet_equation!
+      end
+      
+      private
+      
+      def validate_start_date!
+        unless @start_date.is_a?(Date)
+          raise StartDateValidationError.new(
+            "Model start_date must be a Date, got #{@start_date.class}"
+          )
+        end
+      end
+      
+      def validate_formula_dependencies!
+        # Get all defined variable names
+        defined_vars = @calculator.variable_names.map(&:to_s)
+
+        # Get variable names that are inside categories (not top-level calculated_values)
+        category_variables = @categories.flat_map do |cat|
+          collect_category_variable_names(cat)
+        end.to_set
+
+        # Check all calculated variables for undefined dependencies
+        # Skip top-level calculated_values (those not in any category)
+        @calculator.variables.each do |name, var_def|
+          next unless var_def.is_a?(Hash) && var_def[:type] == :calculated
+          next unless var_def[:formula]
+          next unless category_variables.include?(name.to_sym) || category_variables.include?(name.to_s)
+
+          dependencies = @calculator.extract_variable_dependencies(var_def[:formula])
+          undefined = dependencies.reject { |dep| defined_vars.include?(dep.to_s) }
+
+          if undefined.any?
+            raise UndefinedVariableError.new(
+              "Formula for '#{name}' references undefined variable(s): #{undefined.join(', ')}"
+            )
+          end
+        end
+      end
+
+      def collect_category_variable_names(category)
+        names = category.variables.map { |v| v[:name] }
+        category.children.each do |child|
+          names.concat(collect_category_variable_names(child))
+        end
+        names
+      end
+
+      def validate_balance_sheet_equation!
+        # Calculate total assets (all values are stored as positive)
+        total_assets = @accounts.values.select { |acc| acc.type == :asset }
+          .sum { |acc| acc.opening_balance.to_f }
+        
+        # Calculate total liabilities (all values are stored as positive)
+        total_liabilities = @accounts.values.select { |acc| acc.type == :liability }
+          .sum { |acc| acc.opening_balance.to_f }
+        
+        # Calculate total equity (all values are stored as positive)
+        total_equity = @accounts.values.select { |acc| acc.type == :equity }
+          .sum { |acc| acc.opening_balance.to_f }
+        
+        # Validate: Assets = Liabilities + Equity
+        difference = (total_assets - (total_liabilities + total_equity)).abs
+        
+        unless difference <= 0.01  # Allow small rounding differences
+          raise BalanceSheetValidationError.new(
+            "Balance sheet does not balance: Assets (#{total_assets}) != Liabilities (#{total_liabilities}) + Equity (#{total_equity}). " \
+            "Difference: #{difference}"
+          )
+        end
+      end
+    end
+  end
+end
+

data/lib/fin_it/financial_model/variable_matching.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FinIt
+  class FinancialModel
+    # Variable project matching and filtering
+    module VariableMatching
+      # Check if a variable matches the project filter
+      def variable_matches_project?(variable, project_filter)
+        return true unless project_filter
+        
+        variable_project = get_variable_project(variable[:name])
+        variable_project == project_filter
+      end
+      
+      # Get project tag for a variable
+      def get_variable_project(variable_name)
+        # Check in temporal values metadata
+        temporal_value = @calculator.instance_variable_get(:@temporal_values)[variable_name]
+        if temporal_value
+          # Get project from most recent period metadata
+          periods = temporal_value.instance_variable_get(:@periods)
+          if periods && periods.any?
+            latest_period = periods.last
+            return latest_period[:metadata][:project] if latest_period[:metadata]
+          end
+        end
+        
+        # Check in calculated variables metadata
+        var_def = @calculator.variables[variable_name]
+        if var_def.is_a?(Hash) && var_def[:type] == :calculated
+          return var_def[:project]
+        end
+        
+        # Check in complex models
+        complex_model = @complex_models[variable_name]
+        return complex_model.project if complex_model && complex_model.project
+        
+        # Check in category variables
+        @categories.each do |cat|
+          var = (cat.variables + cat.descendants.flat_map(&:variables)).find { |v| v[:name] == variable_name }
+          return var[:project] if var && var[:project]
+        end
+        
+        nil
+      end
+    end
+  end
+end
+