fin_it 0.1.0

data/lib/fin_it/calculator.rb

@@ -0,0 +1,480 @@
+# frozen_string_literal: true
+
+# Calculator - Pure calculation engine for financial formulas and variables
+#
+# This class handles:
+# - Variable storage and retrieval (drivers, financial, calculated)
+# - Formula evaluation using Dentaku
+# - Temporal value management
+#
+# Concerns extracted to modules:
+# - Calculator::VariableHashing - Variable hash calculation for cache invalidation
+# - Calculator::DateHelpers - Date parsing and period generation
+# - Calculator::CurrencyConversion - Currency conversion and exchange rates
+
+require "dentaku"
+require "money"
+require_relative "payment_schedule"
+
+module FinIt
+  # Calculates values using formulas and temporal values with currency support
+  class Calculator
+    # Calculator concerns - loaded explicitly to show dependencies
+    require_relative "calculator/variable_hashing"
+    require_relative "calculator/date_helpers"
+    require_relative "calculator/currency_conversion"
+    
+    include Calculator::VariableHashing
+    include Calculator::DateHelpers
+    include Calculator::CurrencyConversion
+    attr_reader :variables, :calculator, :default_currency
+
+    def initialize(default_currency: 'USD')
+      @variables = {}
+      @calculator = Dentaku::Calculator.new
+      @temporal_values = {}
+      @default_currency = default_currency
+      
+      # Set up exchange rates (in production, use real rates)
+      configure_exchange_rates
+    end
+
+    # Define a simple variable with a value and currency
+    def define_variable(name, value, currency: nil, frequency: :annual, start_date: nil, end_date: nil, metadata: {}, account: nil, project: nil)
+      # Driver variables (no currency) are stored as-is without frequency conversion
+      is_driver = currency.nil?
+      currency ||= @default_currency if !is_driver
+      
+      # Convert value based on frequency to annual amount for financial variables
+      # Driver variables are not scaled by frequency
+      annualized_value = if is_driver
+        value  # Drivers like employee count don't get scaled
+      else
+        case frequency
+        when :daily
+          value * 365
+        when :weekly
+          value * 52
+        when :monthly
+          value * 12
+        when :quarterly
+          value * 4
+        when :annual
+          value
+        else
+          value
+        end
+      end
+      
+      # Add frequency, account, and project to metadata
+      metadata = metadata.merge(frequency: frequency, account: account, is_driver: is_driver, project: project)
+      
+      @temporal_values[name] ||= TemporalValue.new(name, default_currency: currency)
+      @temporal_values[name].add_period(annualized_value, 
+        start_date: start_date, 
+        end_date: end_date,
+        currency: is_driver ? nil : currency,
+        metadata: metadata
+      )
+      
+      # Store appropriately - Money for financial variables, raw value for drivers
+      @variables[name] = if is_driver
+        annualized_value
+      elsif annualized_value.is_a?(Money)
+        annualized_value
+      else
+        Money.new((annualized_value * 100).to_i, currency)
+      end
+    end
+
+    # Define a calculated variable with a formula
+    def define_calculated(name, formula, start_date: nil, end_date: nil, dependencies: [], round_to: nil, frequency: nil, payment_schedule: nil, project: nil)
+      # Create payment schedule if frequency is specified
+      schedule = nil
+      if frequency && payment_schedule
+        schedule = PaymentSchedule.new(
+          frequency: frequency,
+          payment_schedule: payment_schedule,
+          start_date: start_date,
+          end_date: end_date
+        )
+      end
+      
+      @variables[name] = {
+        type: :calculated,
+        formula: formula,
+        start_date: start_date,
+        end_date: end_date,
+        dependencies: dependencies,
+        round_to: round_to,
+        frequency: frequency,
+        payment_schedule: schedule,
+        project: project
+      }
+    end
+
+    # Calculate a variable's value at a specific date with currency conversion
+    def calculate(name, date: nil, output_currency: nil, context: {}, period_type: :annual)
+      output_currency ||= @default_currency
+      date = parse_date(date) if date
+      
+      # Check if variable has temporal values
+      if @temporal_values[name]
+        return @temporal_values[name].value_at(date || Date.today, output_currency: output_currency, period_type: period_type)
+      end
+      
+      # Check if it's a calculated variable
+      var_def = @variables[name]
+      
+      if var_def.is_a?(Hash) && var_def[:type] == :calculated
+        # Check if this calculation is valid for the given date
+        if date
+          start_ok = var_def[:start_date].nil? || parse_date(var_def[:start_date]) <= date
+          end_ok = var_def[:end_date].nil? || date <= parse_date(var_def[:end_date])
+          
+          return nil unless start_ok && end_ok
+        end
+        
+        # If payment schedule exists, check if this is a payment date
+        if var_def[:payment_schedule]
+          return nil unless var_def[:payment_schedule].payment_date?(date || Date.today)
+        end
+        
+        # Build context with all values in the output currency
+        calc_context = build_currency_context(date, output_currency, period_type: period_type)
+        calc_context.merge!(context)
+        
+        # Evaluate formula
+        result = @calculator.evaluate(var_def[:formula], calc_context)
+        
+        # Convert result to Money
+        result_money = Money.new((result * 100).to_i, output_currency) if result
+        
+        # Round if specified
+        if var_def[:round_to] && result_money
+          fractional = result_money.fractional
+          rounded = fractional.round(-(2 - var_def[:round_to]))
+          result_money = Money.new(rounded, output_currency)
+        end
+        
+        result_money
+      elsif var_def.is_a?(Money)
+        # Simple variable - convert if needed
+        var_def.exchange_to(output_currency)
+      else
+        var_def
+      end
+    end
+
+    # Calculate all values for a date range
+    def calculate_range(start_date, end_date, frequency: :monthly)
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+      
+      results = {}
+      
+      # Generate dates based on frequency
+      dates = generate_dates(start_date, end_date, frequency)
+      
+      dates.each do |date|
+        results[date] = {}
+        
+        @variables.keys.each do |var_name|
+          results[date][var_name] = calculate(var_name, date: date)
+        end
+        
+        # Also include temporal values
+        @temporal_values.keys.each do |var_name|
+          results[date][var_name] ||= @temporal_values[var_name].value_at(date)
+        end
+      end
+      
+      results
+    end
+
+    # Get variable value at a specific date (convenience method)
+    def get(name, date: nil)
+      calculate(name, date: date)
+    end
+
+    # Get all variable names
+    def variable_names
+      (@variables.keys + @temporal_values.keys).uniq
+    end
+    
+    # Extract variable names from a formula string
+    def extract_variable_dependencies(formula)
+      return [] unless formula.is_a?(String)
+      
+      # Use Dentaku to tokenize and extract identifiers
+      tokens = @calculator.tokenize(formula)
+      tokens.select { |token| token.is_a?(Dentaku::Token::Identifier) }.map(&:value).uniq
+    rescue
+      # Fallback: simple regex extraction
+      formula.scan(/\b[a-z_][a-z0-9_]*\b/i).uniq
+    end
+    
+    # Get project tag for a variable
+    def get_variable_project(variable_name)
+      # Normalize to symbol for lookup
+      var_key = variable_name.is_a?(Symbol) ? variable_name : variable_name.to_sym
+      
+      # Check in temporal values metadata
+      temporal_value = @temporal_values[var_key] || @temporal_values[variable_name]
+      if temporal_value
+        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 = @variables[var_key] || @variables[variable_name]
+      if var_def.is_a?(Hash) && var_def[:type] == :calculated
+        return var_def[:project]
+      end
+      
+      nil
+    end
+    
+    def build_currency_context(date, output_currency, period_type: :annual)
+      context = {}
+      
+      # Convert all values to output currency for calculation
+      @temporal_values.each do |name, temporal|
+        value = temporal.value_at(date || Date.today, output_currency: output_currency, period_type: period_type)
+        if value
+          if value.is_a?(Money)
+          # Convert to output currency and get numeric value
+            converted = value.exchange_to(output_currency)
+            context[name] = converted.to_f
+          else
+            # Driver variable - use raw numeric value
+            context[name] = value
+          end
+        end
+      end
+      
+      @variables.each do |name, value|
+        next if value.is_a?(Hash) # Skip calculated - will be resolved recursively
+        next if @temporal_values.key?(name) # Skip if already added from temporal values
+        
+        if value.is_a?(Money)
+          converted = value.exchange_to(output_currency)
+          context[name] = converted.to_f
+        else
+          # Driver variable
+          context[name] = value
+        end
+      end
+      
+      # Recursively resolve calculated variables
+      max_iterations = 20
+      iterations = 0
+      
+      loop do
+        iterations += 1
+        break if iterations > max_iterations
+        
+        changed = false
+        
+        @variables.each do |name, value|
+          next unless value.is_a?(Hash) && value[:type] == :calculated
+          next if context[name] # Already calculated
+          
+          # Check if this calculation is valid for the given date
+          if date
+            start_ok = value[:start_date].nil? || parse_date(value[:start_date]) <= date
+            end_ok = value[:end_date].nil? || date <= parse_date(value[:end_date])
+            next unless start_ok && end_ok
+          end
+          
+          # If payment schedule exists, check if this is a payment date
+          if value[:payment_schedule]
+            next unless value[:payment_schedule].payment_date?(date || Date.today)
+          end
+          
+          # Check if we can calculate this formula now
+          begin
+            result = @calculator.evaluate(value[:formula], context)
+            if result
+              # Convert result to Money and then to float for context
+              result_money = Money.new((result * 100).to_i, output_currency)
+              context[name] = result_money.to_f
+              changed = true
+            end
+          rescue
+            # Can't calculate yet, missing dependencies
+          end
+        end
+        
+        break unless changed
+      end
+      
+      context
+    end
+    
+    def build_context(date)
+      context = {}
+
+      # Add all simple variables
+      @variables.each do |name, value|
+        next if value.is_a?(Hash) # Skip calculated variables
+        context[name] = value.is_a?(Money) ? value.to_f : value
+      end
+
+      # Add temporal values at this date
+      @temporal_values.each do |name, temporal|
+        value = temporal.value_at(date || Date.today)
+        context[name] = value.is_a?(Money) ? value.to_f : value
+      end
+
+      # Recursively resolve calculated variables
+      max_iterations = 10
+      iterations = 0
+
+      loop do
+        iterations += 1
+        break if iterations > max_iterations
+
+        changed = false
+
+        @variables.each do |name, value|
+          next unless value.is_a?(Hash) && value[:type] == :calculated
+          next if context[name] # Already calculated
+
+          # Check if we can calculate this formula now
+          begin
+            result = @calculator.evaluate(value[:formula], context)
+            result = result.round(value[:round_to]) if value[:round_to] && result
+            context[name] = result
+            changed = true
+          rescue
+            # Can't calculate yet, missing dependencies
+          end
+        end
+
+        break unless changed
+      end
+
+      context
+    end
+
+    # Deep clone this calculator for model isolation
+    def deep_clone
+      cloned = Calculator.new(default_currency: @default_currency)
+
+      # Clone temporal values
+      @temporal_values.each do |name, temporal_value|
+        cloned.instance_variable_get(:@temporal_values)[name] = temporal_value.deep_clone
+      end
+
+      # Clone variable definitions
+      @variables.each do |name, var_def|
+        cloned.instance_variable_get(:@variables)[name] = deep_clone_variable_def(var_def)
+      end
+
+      cloned
+    end
+
+    # Override methods for plan application
+
+    # Replace value for a variable
+    def set_override(name, value, start_date: nil, end_date: nil)
+      name = name.to_sym
+      temporal = @temporal_values[name]
+      if temporal
+        temporal.set_period(value, start_date: start_date, end_date: end_date)
+      else
+        # Simple variable - just replace
+        @variables[name] = convert_to_money(value)
+      end
+    end
+
+    # Scale variable by factor
+    def scale_variable(name, factor, start_date: nil, end_date: nil)
+      name = name.to_sym
+      temporal = @temporal_values[name]
+      if temporal
+        temporal.scale_periods(factor, start_date: start_date, end_date: end_date)
+      else
+        current = @variables[name]
+        if current.is_a?(Money)
+          @variables[name] = Money.new((current.fractional * factor).round, current.currency)
+        elsif current.is_a?(Numeric)
+          @variables[name] = current * factor
+        end
+      end
+    end
+
+    # Add/subtract amount
+    def adjust_variable(name, amount, start_date: nil, end_date: nil)
+      name = name.to_sym
+      temporal = @temporal_values[name]
+      if temporal
+        temporal.adjust_periods(amount, start_date: start_date, end_date: end_date)
+      else
+        current = @variables[name]
+        if current.is_a?(Money)
+          @variables[name] = Money.new(current.fractional + (amount * 100).to_i, current.currency)
+        elsif current.is_a?(Numeric)
+          @variables[name] = current + amount
+        end
+      end
+    end
+
+    # Override calculated variable formula
+    def override_formula(name, new_formula, start_date: nil, end_date: nil)
+      name = name.to_sym
+      var_def = @variables[name]
+      return unless var_def.is_a?(Hash) && var_def[:type] == :calculated
+
+      if start_date || end_date
+        # Temporal formula override - store both
+        var_def[:formula_overrides] ||= []
+        var_def[:formula_overrides] << {
+          formula: new_formula,
+          start_date: parse_date(start_date),
+          end_date: parse_date(end_date)
+        }
+      else
+        # Full replacement
+        var_def[:formula] = new_formula
+        var_def[:dependencies] = extract_variable_dependencies(new_formula)
+      end
+    end
+
+    private
+
+    def deep_clone_variable_def(var_def)
+      case var_def
+      when Hash
+        cloned = {}
+        var_def.each do |k, v|
+          cloned[k] = case v
+          when Array then v.map { |item| item.is_a?(Hash) ? item.dup : item }
+          when Hash then v.dup
+          when PaymentSchedule then v.dup
+          else v
+          end
+        end
+        cloned
+      when Money
+        Money.new(var_def.fractional, var_def.currency)
+      else
+        var_def
+      end
+    end
+
+    def convert_to_money(value)
+      if value.is_a?(Money)
+        value
+      else
+        Money.new((value * 100).to_i, @default_currency)
+      end
+    end
+
+  end
+end
+

data/lib/fin_it/categories/category.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module FinIt
+  module Categories
+    class Category
+      FINANCIAL_TYPES = [
+        :income,           # Revenue, sales
+        :expense,          # Operating expenses, COGS
+        :asset,            # Current/fixed assets  
+        :liability,        # Debts, obligations
+        :equity,           # Owner's equity
+        :cash_inflow,      # Operating/investing/financing inflows
+        :cash_outflow      # Operating/investing/financing outflows
+      ].freeze
+      
+      NON_FINANCIAL_TYPES = [
+        :metric,           # KPIs, ratios
+        :driver,           # Employee count, units sold
+        :assumption        # Growth rates, factors
+      ].freeze
+      
+      attr_accessor :name, :type, :parent, :children, :variables, :description, :metadata,
+                    :default_account, :defaults
+
+      def initialize(name, type: nil, parent: nil, description: nil, default_account: nil, defaults: nil)
+        @name = name
+        @parent = parent
+        @children = []
+        @variables = []
+        @description = description
+        @metadata = {}
+
+        # Type can be inherited from parent if not specified
+        resolved_type = type || parent&.type
+        unless resolved_type
+          raise ArgumentError, "Category '#{name}' must specify type: or be nested inside a parent category"
+        end
+        @type = validate_type(resolved_type)
+
+        # Default account - inherit from parent if not specified
+        @default_account = default_account || parent&.default_account
+
+        # Defaults hash (frequency, start_date, end_date) - merge with parent's defaults
+        parent_defaults = parent&.defaults || {}
+        @defaults = parent_defaults.merge(defaults || {})
+      end
+      
+      def financial?
+        FINANCIAL_TYPES.include?(@type)
+      end
+      
+      def non_financial?
+        NON_FINANCIAL_TYPES.include?(@type)
+      end
+      
+      # Get all descendant categories recursively
+      def descendants
+        children + children.flat_map(&:descendants)
+      end
+      
+      # Get all variables including from descendants
+      def all_variables
+        variables + descendants.flat_map(&:variables)
+      end
+      
+      # Calculate total for this category and descendants
+      def total(date: nil, calculator: nil, output_currency: nil)
+        return 0 unless calculator
+        
+        all_variables.sum do |var|
+          value = calculator.calculate(var[:name], date: date, output_currency: output_currency)
+          
+          # Handle Money objects
+          if value.respond_to?(:to_f)
+            value.to_f
+          else
+            value || 0
+          end
+        end
+      end
+      
+      # Get the full path from root to this category
+      def path
+        if parent
+          parent.path + [name]
+        else
+          [name]
+        end
+      end
+      
+      # Find a subcategory by name (recursive)
+      def find_subcategory(name)
+        return self if self.name == name
+        
+        children.each do |child|
+          found = child.find_subcategory(name)
+          return found if found
+        end
+        
+        nil
+      end
+      
+      # Deep clone this category and all descendants
+      def deep_clone(parent: nil)
+        cloned = Category.new(
+          @name,
+          type: @type,
+          parent: parent,
+          description: @description,
+          default_account: @default_account,
+          defaults: @defaults.dup
+        )
+        cloned.metadata = @metadata.dup
+
+        # Clone variables array (deep copy each hash)
+        cloned.variables = @variables.map { |v| v.dup }
+
+        # Recursively clone children
+        @children.each do |child|
+          cloned_child = child.deep_clone(parent: cloned)
+          cloned.children << cloned_child
+        end
+
+        cloned
+      end
+
+      private
+
+      def validate_type(type)
+        unless FINANCIAL_TYPES.include?(type) || NON_FINANCIAL_TYPES.include?(type)
+          raise ArgumentError, "Invalid category type: #{type}. Must be one of: #{(FINANCIAL_TYPES + NON_FINANCIAL_TYPES).join(', ')}"
+        end
+        type
+      end
+    end
+  end
+end