fin_it 0.1.0

data/lib/fin_it/financial_model.rb

@@ -0,0 +1,395 @@
+# frozen_string_literal: true
+
+require 'money'
+require_relative 'transaction_generator'
+require_relative 'financial_model/debugging'
+require_relative 'financial_model/date_helpers'
+require_relative 'financial_model/validation'
+require_relative 'financial_model/currency_helpers'
+require_relative 'financial_model/variable_matching'
+require_relative 'financial_model/account_balances'
+require_relative 'financial_model/period_flows'
+require_relative 'financial_model/category_values'
+require_relative 'financial_model/account_hierarchy'
+
+module FinIt
+  # Custom error for balance sheet validation
+  class BalanceSheetValidationError < StandardError; end
+
+  # Custom error for start date validation
+  class StartDateValidationError < StandardError; end
+
+  # Custom error for undefined variables in formulas
+  class UndefinedVariableError < StandardError; end
+
+  # The built financial model - coordinates calculator, accounts, and transactions
+  class FinancialModel
+    include FinancialModel::Debugging
+    include FinancialModel::DateHelpers
+    include FinancialModel::Validation
+    include FinancialModel::CurrencyHelpers
+    include FinancialModel::VariableMatching
+    include FinancialModel::AccountBalances
+    include FinancialModel::PeriodFlows
+    include FinancialModel::CategoryValues
+    include FinancialModel::AccountHierarchy
+    
+    attr_reader :calculator, :categories, :config, :accounts, :complex_models, :category_accounts
+
+    def initialize(calculator, categories, config, accounts = {}, category_accounts = {})
+      @calculator = calculator
+      @categories = categories
+      @config = config
+      @accounts = accounts
+      @category_accounts = category_accounts # Map category -> account for bidirectional relationship
+      @start_date = config[:start_date]
+      @complex_models = config[:complex_models] || {}
+      @transaction_generator = TransactionGenerator.new(self)
+    end
+
+    # Calculate all values for a specific date
+    def calculate_at(date)
+      result = {}
+      
+      @calculator.variable_names.each do |name|
+        result[name] = @calculator.calculate(name, date: date)
+      end
+      
+      result
+    end
+
+    # Calculate for a date range
+    def calculate_range(start_date, end_date, frequency: :monthly)
+      @calculator.calculate_range(start_date, end_date, frequency: frequency)
+    end
+
+    # Get a specific value
+    def get(name, date: nil)
+      @calculator.get(name, date: date)
+    end
+
+    # Generate a report
+    def to_report(date: nil)
+      calculate_at(date || Date.today)
+    end
+
+    # Export to hash
+    def to_h
+      {
+        config: @config,
+        categories: @categories,
+        values: to_report
+      }
+    end
+    
+    # Get start date
+    def start_date
+      @start_date
+    end
+    
+    # Generate all transactions up to end_date
+    def generate_transactions(end_date)
+      @transaction_generator.generate_transactions(end_date)
+    end
+    
+    # Query transactions
+    def transactions(date_range: nil, account: nil, variable: nil)
+      @transaction_generator.transactions(
+        date_range: date_range,
+        account: account,
+        variable: variable
+      )
+    end
+    
+    # Get variable value for a specific period
+    def variable_value(variable_name, date:, period_type: :annual)
+      @calculator.calculate(
+        variable_name,
+        date: date,
+        output_currency: @config[:default_currency],
+        period_type: period_type
+      )
+    end
+    
+    # Check if transaction cache is valid
+    def transaction_cache_valid?
+      @transaction_generator.cache_valid?
+    end
+    
+    # Calculate period net income (Income - Expenses) for a date range
+    def period_net_income(start_date, end_date, output_currency: nil, filters: {})
+      output_currency ||= @config[:default_currency]
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+
+      # Get all income categories
+      income_categories = @categories.select { |c| c.type == :income }
+
+      # Get all expense categories
+      expense_categories = @categories.select { |c| c.type == :expense }
+
+      # Calculate total income for the period using account hierarchy
+      total_income = income_categories.sum do |category|
+        category_total_via_account(
+          category,
+          start_date,
+          end_date,
+          period_type: :annual,
+          output_currency: output_currency,
+          filters: filters,
+          use_balance: false
+        )
+      end
+
+      # Calculate total expenses for the period using account hierarchy
+      # Note: account flows for expenses are negative (debits), so we need to take absolute value
+      total_expenses = expense_categories.sum do |category|
+        expense_value = category_total_via_account(
+          category,
+          start_date,
+          end_date,
+          period_type: :annual,
+          output_currency: output_currency,
+          filters: filters,
+          use_balance: false
+        )
+        # Expense account flows are negative, so take absolute value for calculation
+        expense_value.abs
+      end
+
+      # Net income = Income - Expenses
+      net_income = total_income - total_expenses
+
+      # Convert to float if Money object
+      net_income.is_a?(Money) ? net_income.to_f : net_income.to_f
+    end
+
+    # ========== Plan/Scenario Methods ==========
+
+    # Get all defined plans
+    def plans
+      @config[:plans] || {}
+    end
+
+    # Apply a single plan and return a new isolated model
+    # @param plan_or_name [Plan, Symbol] The plan object or name of a registered plan
+    # @return [FinancialModel] A new model with the plan applied
+    def with_plan(plan_or_name)
+      plan = resolve_plan(plan_or_name)
+      raise ArgumentError, "Plan not found: #{plan_or_name}" unless plan
+
+      cloned = clone_model
+      cloned.apply_plan!(plan)
+      cloned
+    end
+
+    # Apply multiple plans in order and return a new isolated model
+    # Later plans override earlier ones on conflicts
+    # @param plan_names [Array<Symbol, Plan>] The plans to apply
+    # @return [FinancialModel] A new model with all plans applied
+    def with_plans(*plan_names)
+      cloned = clone_model
+      plan_names.flatten.each do |plan_or_name|
+        plan = resolve_plan(plan_or_name)
+        raise ArgumentError, "Plan not found: #{plan_or_name}" unless plan
+        cloned.apply_plan!(plan)
+      end
+      cloned
+    end
+
+    # Apply a plan to this model (mutates this instance)
+    # @param plan [Plan] The plan to apply
+    # @return [self]
+    def apply_plan!(plan)
+      plan.overrides.each do |override|
+        apply_override(override, plan)
+      end
+      @transaction_generator.invalidate_cache! if @transaction_generator.respond_to?(:invalidate_cache!)
+      self
+    end
+
+    # Create a deep clone of this model for isolation
+    # @return [FinancialModel] A new independent model
+    def clone_model
+      cloned_calculator = @calculator.deep_clone
+      cloned_categories = deep_clone_categories(@categories)
+      cloned_accounts = deep_clone_accounts(@accounts)
+      cloned_category_accounts = rebuild_category_accounts(cloned_categories, cloned_accounts)
+
+      cloned_config = @config.dup
+      cloned_config[:plans] = @config[:plans]&.transform_values(&:dup)
+      cloned_config[:complex_models] = @config[:complex_models]&.transform_values(&:dup)
+
+      FinancialModel.new(
+        cloned_calculator,
+        cloned_categories,
+        cloned_config,
+        cloned_accounts,
+        cloned_category_accounts
+      )
+    end
+
+    private
+
+    def resolve_plan(plan_or_name)
+      case plan_or_name
+      when Plan
+        plan_or_name
+      when Symbol, String
+        plans[plan_or_name.to_sym]
+      else
+        nil
+      end
+    end
+
+    def apply_override(override, plan)
+      var_name = override[:variable]
+      start_date = override[:start_date] || plan.start_date
+      end_date = override[:end_date] || plan.end_date
+
+      case override[:type]
+      when :set
+        @calculator.set_override(var_name, override[:value],
+                                 start_date: start_date, end_date: end_date)
+      when :scale
+        @calculator.scale_variable(var_name, override[:factor],
+                                   start_date: start_date, end_date: end_date)
+      when :adjust
+        @calculator.adjust_variable(var_name, override[:amount],
+                                    start_date: start_date, end_date: end_date)
+      when :formula
+        @calculator.override_formula(var_name, override[:formula],
+                                     start_date: start_date, end_date: end_date)
+      when :opening_balance
+        account = @accounts[override[:account]]
+        raise ArgumentError, "Account not found: #{override[:account]}" unless account
+        account.instance_variable_set(:@opening_balance, override[:amount])
+      when :add_variable
+        add_variable_from_override(override, plan)
+      when :add_calculated
+        add_calculated_from_override(override, plan)
+      end
+    end
+
+    def add_variable_from_override(override, plan)
+      # Find category
+      category = find_category_by_name(override[:category])
+      return unless category
+
+      # Create a simple variable builder context
+      var_builder = VariableBuilderContext.new
+      override[:block]&.call(var_builder)
+
+      # Add to calculator
+      @calculator.define_variable(
+        override[:name],
+        var_builder.value_amount,
+        currency: override[:currency] || @config[:default_currency],
+        frequency: var_builder.frequency || :monthly,
+        start_date: var_builder.start_date || plan.start_date,
+        end_date: var_builder.end_date || plan.end_date
+      )
+
+      # Add to category's variables
+      category.variables << {
+        name: override[:name],
+        type: :financial,
+        currency: override[:currency] || @config[:default_currency],
+        frequency: var_builder.frequency || :monthly
+      }
+    end
+
+    def add_calculated_from_override(override, plan)
+      category = find_category_by_name(override[:category])
+      return unless category
+
+      options = override[:options] || {}
+      @calculator.define_calculated(
+        override[:name],
+        override[:formula],
+        start_date: options[:start_date] || plan.start_date,
+        end_date: options[:end_date] || plan.end_date
+      )
+
+      category.variables << {
+        name: override[:name],
+        type: :calculated,
+        formula: override[:formula]
+      }
+    end
+
+    def find_category_by_name(name)
+      name = name.to_sym
+      @categories.each do |cat|
+        return cat if cat.name == name
+        found = cat.find_subcategory(name)
+        return found if found
+      end
+      nil
+    end
+
+    def deep_clone_categories(categories)
+      categories.map { |cat| cat.deep_clone }
+    end
+
+    def deep_clone_accounts(accounts)
+      cloned = {}
+      accounts.each do |name, account|
+        cloned[name] = account.deep_clone
+      end
+
+      # Rebuild parent-child relationships
+      accounts.each do |name, original_account|
+        if original_account.parent
+          cloned[name].instance_variable_set(:@parent, cloned[original_account.parent.name])
+          cloned[original_account.parent.name].children << cloned[name]
+        end
+      end
+
+      cloned
+    end
+
+    def rebuild_category_accounts(cloned_categories, cloned_accounts)
+      result = {}
+      @category_accounts.each do |original_cat, original_account|
+        # Find corresponding cloned category
+        cloned_cat = find_cloned_category(cloned_categories, original_cat.name)
+        if cloned_cat && cloned_accounts[original_account.name]
+          result[cloned_cat] = cloned_accounts[original_account.name]
+        end
+      end
+      result
+    end
+
+    def find_cloned_category(categories, name)
+      categories.each do |cat|
+        return cat if cat.name == name
+        found = cat.find_subcategory(name)
+        return found if found
+      end
+      nil
+    end
+  end
+
+  # Simple context for building variables from plan overrides
+  class VariableBuilderContext
+    attr_reader :value_amount, :frequency, :start_date, :end_date
+
+    def initialize
+      @value_amount = 0
+      @frequency = :monthly
+    end
+
+    def value(amount, start_date: nil, end_date: nil)
+      @value_amount = amount
+      @start_date = start_date
+      @end_date = end_date
+    end
+
+    def frequency=(freq)
+      @frequency = freq
+    end
+  end
+end
+
+

data/lib/fin_it/model_template.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module FinIt
+  # Template for reusable complex models (e.g., mortgage payment template)
+  class ModelTemplate
+    attr_reader :name, :variables, :default_debit_accounts, :default_credit_accounts, :calculation_block
+    
+    def initialize(name)
+      @name = name
+      @variables = []
+      @default_debit_accounts = []
+      @default_credit_accounts = []
+      @calculation_block = nil
+    end
+    
+    def add_variable(var_name)
+      @variables << var_name.to_sym
+    end
+    
+    def set_default_debit_accounts(accounts)
+      @default_debit_accounts = Array(accounts).map(&:to_sym)
+    end
+    
+    def set_default_credit_accounts(accounts)
+      @default_credit_accounts = Array(accounts).map(&:to_sym)
+    end
+    
+    def set_calculation(&block)
+      @calculation_block = block
+    end
+    
+    # Instantiate this template as a ComplexModel
+    def instantiate(instance_name, params = {}, accounts: nil, default_currency: 'USD', &block)
+      # Extract reserved params
+      start_date = params.delete(:start_date) || params.delete('start_date')
+      end_date = params.delete(:end_date) || params.delete('end_date')
+      frequency = params.delete(:frequency) || params.delete('frequency') || :monthly
+      debit_account = params.delete(:debit_account) || params.delete('debit_account') || @default_debit_accounts.first
+      credit_account = params.delete(:credit_account) || params.delete('credit_account') || @default_credit_accounts.first
+      project = params.delete(:project) || params.delete('project')
+      
+      # Auto-create debit_account if it doesn't exist
+      if debit_account && accounts
+        debit_account = ensure_account_exists(debit_account, accounts, default_currency: default_currency)
+      end
+      
+      # Remaining params become input variables
+      input_variables = params
+      
+      # If debit_account is a template variable, add it to input_variables with the resolved account name
+      if @variables.include?(:debit_account) && debit_account
+        input_variables[:debit_account] = debit_account
+      end
+      
+      # If credit_account is a template variable, add it to input_variables
+      if @variables.include?(:credit_account) && credit_account
+        input_variables[:credit_account] = credit_account
+      end
+      
+      # Validate required variables are provided
+      missing_vars = @variables - input_variables.keys.map(&:to_sym)
+      if missing_vars.any?
+        raise ArgumentError, "Missing required variables for #{@name}: #{missing_vars.join(', ')}"
+      end
+      
+      # Create ComplexModel with wrapped calculation block
+      require_relative 'complex_model'
+      ComplexModel.new(
+        instance_name,
+        start_date: start_date,
+        end_date: end_date,
+        frequency: frequency,
+        debit_account: debit_account,
+        credit_account: credit_account,
+        project: project
+      ) do |date, context|
+        # Merge template input variables into context
+        full_context = input_variables.merge(context)
+        # Call template's calculation block
+        @calculation_block.call(date, full_context)
+      end.tap do |model|
+        # Set input variables
+        input_variables.each do |key, value|
+          model.input_variable(key, value)
+        end
+      end
+    end
+    
+    private
+    
+    # Ensure account exists, creating it if necessary
+    # Supports array notation for nested accounts (e.g., [:expense, :loan_interest, :vendor_loan])
+    # but only creates the final account for now
+    def ensure_account_exists(account_name, accounts_hash, default_currency: 'USD')
+      # Handle array notation - extract the final account name
+      actual_account_name = if account_name.is_a?(Array)
+        account_name.last
+      else
+        account_name
+      end
+      
+      # Convert to symbol if needed
+      actual_account_name = actual_account_name.to_sym
+      
+      # Check if account already exists
+      return actual_account_name if accounts_hash.key?(actual_account_name)
+      
+      # Create the account as equity type (default for expense accounts)
+      require_relative 'account'
+      new_account = Account.new(
+        actual_account_name,
+        type: :equity,
+        currency: default_currency,
+        opening_balance: 0
+      )
+      
+      accounts_hash[actual_account_name] = new_account
+      actual_account_name
+    end
+  end
+end

data/lib/fin_it/outputs/base_output.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module FinIt
+  module Outputs
+    class BaseOutput
+      attr_reader :report, :options
+      
+      def initialize(report, options = {})
+        @report = report
+        @options = options
+      end
+      
+      def generate
+        raise NotImplementedError, "Subclasses must implement generate"
+      end
+      
+      protected
+      
+      def format_number(num)
+        return "N/A" if num.nil?
+        
+        if num.is_a?(Money)
+          num.format(symbol: false, thousands_separator: ',')
+        else
+          num.to_i.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+        end
+      end
+      
+      def currency_symbol(currency)
+        case currency.to_s
+        when 'USD' then '$'
+        when 'EUR' then '€'
+        when 'MXN' then 'MXN'
+        when 'GBP' then '£'
+        when 'JPY' then '¥'
+        else currency.to_s + ' '
+        end
+      end
+      
+      def format_currency(value, currency = nil)
+        currency ||= @report.output_currency
+        
+        if value.is_a?(Money)
+          "#{currency_symbol(value.currency.iso_code)}#{format_number(value)}"
+        else
+          "#{currency_symbol(currency)}#{format_number(value)}"
+        end
+      end
+    end
+  end
+end