fin_it 0.1.0

data/lib/fin_it/dsl/model_builder.rb

@@ -0,0 +1,938 @@
+# frozen_string_literal: true
+
+require_relative 'variable_builder'
+require_relative 'calculated_builder'
+require_relative 'account_builder'
+require_relative 'config_builder'
+require_relative 'project_inheritance_resolver'
+require_relative 'plan_builder'
+require_relative '../account'
+require_relative '../categories/category'
+
+module FinIt
+  module DSL
+    # DSL for defining financial models
+    class ModelBuilder
+      attr_reader :calculator, :categories, :accounts
+
+      def initialize(default_currency: 'USD')
+        @calculator = Calculator.new(default_currency: default_currency)
+        @categories = []
+        @accounts = {}
+        @category_accounts = {} # Map category -> account for bidirectional relationship
+        @current_category = nil
+        @config = { default_currency: default_currency }
+        @config[:model_templates] = {}
+        @config[:complex_models] = {}
+      end
+
+      # Configuration block
+      def config(&block)
+        config_builder = ConfigBuilder.new(@config)
+        config_builder.instance_eval(&block)
+      end
+
+      # Define an account
+      def account(name, &block)
+        account_builder = AccountBuilder.new(name)
+        account_builder.instance_eval(&block) if block_given?
+        
+        # If inside a category block, inherit type from category if not explicitly set
+        inherited_type = nil
+        if @current_category
+          category_type = @current_category.type
+          if [:asset, :liability, :equity].include?(category_type)
+            inherited_type = category_type
+          end
+        end
+        
+        # Use explicit type if provided, otherwise use inherited type
+        account_type = account_builder.account_type || inherited_type
+        
+        # Type is required - raise error if neither explicit nor inherited
+        unless account_type
+          raise ArgumentError, "Account '#{name}' must specify type: or be defined within an asset/liability/equity category"
+        end
+        
+        account_obj = Account.new(
+          name,
+          type: account_type,
+          currency: account_builder.account_currency || @config[:default_currency],
+          opening_balance: account_builder.account_opening_balance || 0,
+          opening_balance_credit_account: account_builder.account_opening_balance_credit_account || :equity
+        )
+        
+        @accounts[name] = account_obj
+        
+        # If inside a category block, automatically create a variable that references this account
+        if @current_category && [:asset, :liability, :equity].include?(@current_category.type)
+          # Create variable with account name directly (no "_balance" suffix)
+          var_data = {
+            name: name,
+            type: :financial,
+            frequency: :annual,
+            currency: account_obj.currency,
+            account: name,
+            description: account_obj.name.to_s.humanize
+          }
+          @current_category.variables << var_data
+        end
+      end
+
+      # Define a scenario plan
+      # @param name [Symbol] The plan name
+      # @param description [String] Optional description
+      # @param start_date [Date, String, nil] When plan applies
+      # @param end_date [Date, String, nil] When plan ends
+      def plan(name, description: nil, start_date: nil, end_date: nil, &block)
+        plan_builder = PlanBuilder.new(name, description: description,
+                                       start_date: start_date, end_date: end_date)
+        plan_builder.instance_eval(&block) if block_given?
+
+        @config[:plans] ||= {}
+        @config[:plans][name.to_sym] = plan_builder.build
+      end
+
+      # Define a category with type (can be nested)
+      # Type is optional for nested categories - inherits from parent
+      # default_account: account used by children unless overridden
+      # defaults: { frequency:, start_date:, end_date: } inherited by children
+      def category(name, type: nil, description: nil, comments: nil, default_account: nil, defaults: nil, &block)
+        # Determine parent for inheritance
+        parent_category = @current_category
+
+        # Create category - type inheritance happens in Category constructor
+        category_obj = Categories::Category.new(
+          name,
+          type: type,
+          parent: parent_category,
+          description: description,
+          default_account: default_account,
+          defaults: defaults
+        )
+        category_obj.metadata[:comments] = comments if comments
+
+        # Add to parent's children or top-level categories
+        if parent_category
+          parent_category.children << category_obj
+        else
+          @categories << category_obj
+        end
+        
+        # Create account for category (except non-financial categories: driver, metric, assumption)
+        non_financial_types = [:driver, :metric, :assumption]
+        unless non_financial_types.include?(category_obj.type)
+          parent_account = nil
+          if @current_category && !non_financial_types.include?(@current_category.type)
+            parent_account = get_or_create_category_account(@current_category)
+          end
+          category_account = get_or_create_category_account(category_obj, parent_account: parent_account)
+          @category_accounts[category_obj] = category_account
+        end
+        
+        old_category = @current_category
+        @current_category = category_obj
+        
+        instance_eval(&block) if block_given?
+        
+        @current_category = old_category
+      end
+
+      # Define driver variables (non-financial assumptions)
+      # This is a convenience method that creates a driver category and allows defining variables within it
+      def driver(description: nil, &block)
+        # Check if driver category already exists
+        driver_category = @categories.find { |c| c.name == :drivers && c.parent.nil? }
+        
+        unless driver_category
+          driver_category = Categories::Category.new(:drivers, type: :driver, description: description || "Business drivers")
+          @categories << driver_category
+        end
+        
+        old_category = @current_category
+        @current_category = driver_category
+        
+        instance_eval(&block) if block_given?
+        
+        @current_category = old_category
+      end
+
+      # Define a variable with currency support
+      def variable(name, type: :financial, frequency: nil, currency: nil, description: nil, unit: nil, account: nil, project: nil, &block)
+        # Driver variables can have no currency, financial variables get default currency
+        is_driver = @current_category && @current_category.type == :driver
+        currency = nil if is_driver
+        currency ||= @config[:default_currency] unless is_driver
+
+        # Apply defaults from category
+        category_defaults = @current_category&.defaults || {}
+        frequency ||= category_defaults[:frequency] || :annual
+        account ||= @current_category&.default_account
+
+        # Skip account creation for driver variables
+        pl_account = nil  # P&L account for income/expense tracking
+        unless is_driver
+          user_specified_account = account  # Preserve user's account reference
+
+          # Auto-create account for variable as sub-account of category's account
+          if @current_category && [:income, :expense, :asset, :liability, :equity].include?(@current_category.type)
+            category_account = get_or_create_category_account(@current_category)
+            variable_account = create_variable_account(name, @current_category.type, category_account, currency)
+
+            # For income/expense:
+            # - account = user's asset account (where money flows to/from, e.g. :checking)
+            #   If not specified, leave nil so transaction generator uses default asset account
+            # - pl_account = auto-created P&L account (for income statement, e.g. :salary)
+            # For asset/liability/equity:
+            # - account = user's account if specified (e.g. :checking), otherwise the variable account
+            # This allows users to define variables that reference existing accounts for balance sheet reporting
+            if [:income, :expense].include?(@current_category.type)
+              pl_account = variable_account.name  # Store P&L account for transaction generation
+              # Keep user's account or nil - don't fall back to P&L account
+              # Transaction generator will use default asset if nil
+              account = user_specified_account
+            else
+              # For balance sheet categories, preserve user's account reference if specified
+              account = user_specified_account || variable_account.name
+            end
+          elsif account && !@accounts.key?(account.is_a?(Array) ? account.last : account)
+            # Legacy: auto-create account if specified but doesn't exist
+            if @current_category && [:income, :expense].include?(@current_category.type)
+              account = ensure_account_exists(account, @current_category.type)
+            else
+              raise AccountNotFoundError.new(account)
+            end
+          end
+        end
+
+        var_builder = VariableBuilder.new(name, @calculator, currency, frequency: frequency, account: account, project: project)
+        var_builder.instance_eval(&block) if block_given?
+
+        var_data = {
+          name: name,
+          type: type,
+          frequency: frequency,
+          currency: currency,
+          description: description,
+          unit: unit,
+          account: account,
+          pl_account: pl_account,  # P&L account for income/expense tracking
+          project: project
+        }
+        
+        @current_category.variables << var_data if @current_category
+      end
+
+      # Define a calculated variable with formula
+      def calculated(name, formula: nil, description: nil, round_to: nil, start_date: nil, end_date: nil, frequency: nil, payment_schedule: nil, debit_account: nil, credit_account: nil, account: nil, &block)
+        # Apply defaults from category
+        category_defaults = @current_category&.defaults || {}
+        account ||= @current_category&.default_account
+        frequency ||= category_defaults[:frequency]
+        start_date ||= category_defaults[:start_date]
+        end_date ||= category_defaults[:end_date]
+
+        final_formula = nil
+        final_frequency = frequency
+        final_payment_schedule = payment_schedule
+        final_start_date = start_date
+        final_end_date = end_date
+        final_round_to = round_to
+        
+        # Auto-create account for calculated variable as sub-account of category's account
+        # Skip for driver categories
+        calculated_account = nil
+        if @current_category && @current_category.type != :driver && [:income, :expense, :asset, :liability, :equity].include?(@current_category.type)
+          category_account = get_or_create_category_account(@current_category)
+          calculated_account = create_variable_account(name, @current_category.type, category_account, @config[:default_currency])
+        end
+        
+        # Handle convenience 'account:' parameter - sets debit/credit based on category type
+        # For asset/liability/equity categories, store account directly for balance sheet reporting
+        # Auto-create accounts if they don't exist (for income/expense categories)
+        final_account = nil
+        if account && !debit_account && !credit_account && @current_category
+          if @current_category.type == :income
+            # For income: Debit asset (where money goes), Credit income P&L account
+            # - final_debit_account = asset account (user-specified via 'account' param)
+            # - final_credit_account = P&L income account (auto-created)
+            final_debit_account = account
+            final_credit_account = calculated_account ? calculated_account.name : nil
+            # Auto-create P&L account if it doesn't exist
+            if final_credit_account && !@accounts.key?(final_credit_account.is_a?(Array) ? final_credit_account.last : final_credit_account) && [:income, :expense].include?(@current_category.type)
+              final_credit_account = ensure_account_exists(final_credit_account, @current_category.type)
+            end
+          elsif @current_category.type == :expense
+            # For expenses: Debit expense P&L account, Credit asset/liability (where money comes from)
+            # - final_debit_account = P&L expense account (auto-created)
+            # - final_credit_account = asset/liability account (user-specified via 'account' param)
+            final_debit_account = calculated_account ? calculated_account.name : nil
+            if final_debit_account && !@accounts.key?(final_debit_account.is_a?(Array) ? final_debit_account.last : final_debit_account) && [:income, :expense].include?(@current_category.type)
+              final_debit_account = ensure_account_exists(final_debit_account, @current_category.type)
+            end
+            # Use user-specified account as credit (asset/liability where money comes from)
+            final_credit_account = account
+          else
+            # For asset/liability/equity categories, use calculated account if created
+            final_account = calculated_account ? calculated_account.name : account
+            final_debit_account = debit_account
+            final_credit_account = credit_account
+          end
+        else
+          # Handle explicit debit_account/credit_account parameters
+          # For income: credit_account is asset account, variable's account is income account
+          # For expense: debit_account is asset account, variable's account is expense account
+          if @current_category
+            if @current_category.type == :income
+              # Income: Debit asset (credit_account param), Credit income (variable's account)
+              if credit_account
+                final_debit_account = credit_account # Asset account where money goes
+                final_credit_account = calculated_account ? calculated_account.name : find_equity_account # Income account
+              elsif debit_account
+                final_debit_account = debit_account
+                final_credit_account = calculated_account ? calculated_account.name : find_equity_account
+              elsif calculated_account
+                final_debit_account = find_default_asset_account
+                final_credit_account = calculated_account.name
+              end
+            elsif @current_category.type == :expense
+              # Expense: Debit expense (variable's account), Credit asset (debit_account param)
+              if debit_account
+                final_debit_account = calculated_account ? calculated_account.name : find_equity_account # Expense account
+                final_credit_account = debit_account # Asset account where money comes from
+              elsif credit_account
+                final_debit_account = calculated_account ? calculated_account.name : find_equity_account
+                final_credit_account = credit_account
+              elsif calculated_account
+                final_debit_account = calculated_account.name
+                final_credit_account = find_default_asset_account
+              end
+            end
+          end
+          
+          # Auto-create accounts if they don't exist (for asset accounts)
+          if final_debit_account && !@accounts.key?(final_debit_account.is_a?(Array) ? final_debit_account.last : final_debit_account)
+            if @current_category && [:income, :expense].include?(@current_category.type)
+              # Only auto-create if it's an asset account (not income/expense)
+              account_obj = @accounts[final_debit_account.is_a?(Array) ? final_debit_account.last : final_debit_account]
+              unless account_obj && [:income, :expense].include?(account_obj.type)
+                final_debit_account = ensure_account_exists(final_debit_account, @current_category.type)
+              end
+            end
+          end
+          if final_credit_account && !@accounts.key?(final_credit_account.is_a?(Array) ? final_credit_account.last : final_credit_account)
+            if @current_category && [:income, :expense].include?(@current_category.type)
+              # Only auto-create if it's an asset account (not income/expense)
+              account_obj = @accounts[final_credit_account.is_a?(Array) ? final_credit_account.last : final_credit_account]
+              unless account_obj && [:income, :expense].include?(account_obj.type)
+                final_credit_account = ensure_account_exists(final_credit_account, @current_category.type)
+              end
+            end
+          end
+          final_account = account if account
+        end
+        
+        if formula
+          # Inline syntax: calculated(:name, formula: "a + b")
+          final_formula = formula
+        elsif block_given?
+          # Block syntax: calculated(:name) do formula "a + b" end
+          calc_builder = CalculatedBuilder.new(name, @calculator)
+          calc_builder.instance_eval(&block)
+          
+          # Use block values or parameters, with parameters taking precedence
+          final_frequency = frequency || calc_builder.frequency
+          final_payment_schedule = payment_schedule || calc_builder.payment_schedule
+          final_start_date = start_date || calc_builder.start_date
+          final_end_date = end_date || calc_builder.end_date
+          final_round_to = round_to || calc_builder.round_to
+          final_formula = calc_builder.formula
+          
+          # Handle account from block if not already set from keyword args
+          if calc_builder.account && !final_debit_account && !final_credit_account && @current_category
+            if @current_category.type == :income
+              # Auto-create account if it doesn't exist
+              if !@accounts.key?(calc_builder.account.is_a?(Array) ? calc_builder.account.last : calc_builder.account) && [:income, :expense].include?(@current_category.type)
+                final_credit_account = ensure_account_exists(calc_builder.account, @current_category.type)
+              else
+                final_credit_account = calc_builder.account
+              end
+            elsif @current_category.type == :expense
+              # Auto-create account if it doesn't exist
+              if !@accounts.key?(calc_builder.account.is_a?(Array) ? calc_builder.account.last : calc_builder.account) && [:income, :expense].include?(@current_category.type)
+                final_debit_account = ensure_account_exists(calc_builder.account, @current_category.type)
+              else
+                final_debit_account = calc_builder.account
+              end
+            end
+          end
+          
+          # Auto-create accounts from builder if they don't exist
+          if calc_builder.debit_account && !final_debit_account
+            if !@accounts.key?(calc_builder.debit_account.is_a?(Array) ? calc_builder.debit_account.last : calc_builder.debit_account) && @current_category && [:income, :expense].include?(@current_category.type)
+              final_debit_account = ensure_account_exists(calc_builder.debit_account, @current_category.type)
+            else
+              final_debit_account = calc_builder.debit_account
+            end
+          end
+          if calc_builder.credit_account && !final_credit_account
+            if !@accounts.key?(calc_builder.credit_account.is_a?(Array) ? calc_builder.credit_account.last : calc_builder.credit_account) && @current_category && [:income, :expense].include?(@current_category.type)
+              final_credit_account = ensure_account_exists(calc_builder.credit_account, @current_category.type)
+            else
+              final_credit_account = calc_builder.credit_account
+            end
+          end
+        end
+        
+        # Auto-inherit project tag from dependencies
+        inherited_project = nil
+        if final_formula
+          dependencies = @calculator.extract_variable_dependencies(final_formula)
+          if dependencies.any?
+            resolver = ProjectInheritanceResolver.new(@calculator)
+            inherited_project = resolver.resolve_project(dependencies)
+          end
+        end
+        
+        if final_formula
+          @calculator.define_calculated(
+            name,
+            final_formula,
+            start_date: final_start_date,
+            end_date: final_end_date,
+            round_to: final_round_to,
+            frequency: final_frequency,
+            payment_schedule: final_payment_schedule,
+            project: inherited_project
+          )
+        end
+        
+        var_data = {
+          name: name,
+          type: :calculated,
+          description: description,
+          formula: final_formula,
+          start_date: final_start_date,
+          end_date: final_end_date,
+          frequency: final_frequency,
+          payment_schedule: final_payment_schedule,
+          debit_account: final_debit_account,
+          credit_account: final_credit_account,
+          account: final_account,
+          project: inherited_project
+        }
+        
+        @current_category.variables << var_data if @current_category
+      end
+      
+      # Define a top-level calculated value (outside categories, can be non-financial)
+      def calculated_value(name, formula:, description: nil, round_to: nil, start_date: nil, end_date: nil, frequency: nil, &block)
+        # Top-level calculated values don't require accounts
+        @calculator.define_calculated(
+          name,
+          formula,
+          start_date: start_date,
+          end_date: end_date,
+          round_to: round_to,
+          frequency: frequency
+        )
+      end
+      
+      # Define a reusable model template
+      def define_model(template_name, &block)
+        require_relative '../model_template'
+        require_relative 'model_template_builder'
+        
+        template = ModelTemplate.new(template_name)
+        builder = ModelTemplateBuilder.new(template)
+        builder.instance_eval(&block)
+        
+        # Store template
+        @config[:model_templates] ||= {}
+        @config[:model_templates][template_name] = template
+        
+        # Create dynamic method for instantiation
+        define_singleton_method(template_name) do |instance_name = nil, &instantiation_block|
+          instance_name ||= "#{template_name}_#{@config[:complex_models]&.length.to_i + 1}".to_sym
+          
+          # Parse instantiation block parameters
+          params = {}
+          if instantiation_block
+            # Evaluate block in a context that captures keyword arguments
+            param_capture = ParamCapture.new
+            param_capture.instance_eval(&instantiation_block)
+            params = param_capture.params
+          end
+          
+          # Instantiate template with accounts reference for auto-creation
+          model = template.instantiate(
+            instance_name,
+            params,
+            accounts: @accounts,
+            default_currency: @config[:default_currency] || 'USD'
+          )
+          
+          # Store complex model instance
+          @config[:complex_models] ||= {}
+          @config[:complex_models][instance_name] = model
+          
+          model
+        end
+        
+        template
+      end
+      
+      # Helper class to capture parameters from instantiation block
+      class ParamCapture
+        attr_reader :params
+        
+        def initialize
+          @params = {}
+        end
+        
+        def method_missing(name, *args, &block)
+          if args.length == 1
+            @params[name] = args.first
+          elsif args.empty? && block_given?
+            @params[name] = block
+          else
+            @params[name] = args
+          end
+        end
+        
+        def respond_to_missing?(name, include_private = false)
+          true
+        end
+      end
+
+      # Build the final model
+      def build
+        # Set default start_date if not provided (start of current year)
+        unless @config[:start_date]
+          @config[:start_date] = Date.new(Date.today.year, 1, 1)
+          warn "Warning: No start_date specified. Defaulting to start of current year: #{@config[:start_date]}\n#{caller.join("\n")}"
+        end
+        
+        # Ensure we have an equity account
+        ensure_equity_account
+        
+        # Validate all variables in income/expense categories have required accounts
+        validate_category_variables!
+        
+        # Validate and create model
+        model = FinancialModel.new(@calculator, @categories, @config, @accounts, @category_accounts)
+        
+        # Validate model
+        model.validate!
+        
+        model
+      end
+      
+      # Get model templates (for testing/debugging)
+      def model_templates
+        @config[:model_templates] || {}
+      end
+      
+      private
+      
+      def ensure_equity_account
+        # Calculate balance needed for equity to balance the sheet
+        # All values are stored as positive: Assets = Liabilities + Equity
+        total_assets = @accounts.values.select { |acc| acc.type == :asset }
+          .sum { |acc| acc.opening_balance.to_f }
+        total_liabilities = @accounts.values.select { |acc| acc.type == :liability }
+          .sum { |acc| acc.opening_balance.to_f }
+        
+        # Equity = Assets - Liabilities (to balance the sheet)
+        equity_balance = total_assets - total_liabilities
+        
+        # Check if the main equity account exists (not just any equity account)
+        # Expense accounts are also equity type, but we need the main :equity account
+        has_main_equity = @accounts.key?(:equity)
+        
+        # Also check if there's an equity category (by type, not name)
+        has_equity_category = find_category_by_type(:equity)
+        
+        if has_main_equity
+          # Equity account exists - update its balance
+          existing_equity = @accounts[:equity]
+          # Always update balance to ensure it's correct (accounts may have been created with 0 balance)
+          existing_equity.instance_variable_set(:@opening_balance, equity_balance)
+          equity_account = existing_equity
+        else
+          # Get or create equity category account if equity category exists
+          parent_account = nil
+          if has_equity_category
+            parent_account = get_or_create_category_account(has_equity_category)
+            # If category account is :equity, use it and update balance
+            if parent_account.name == :equity
+              parent_account.instance_variable_set(:@opening_balance, equity_balance)
+              @accounts[:equity] = parent_account
+              equity_account = parent_account
+            else
+              # Create default equity account with calculated balance
+              equity_account = Account.new(
+                :equity,
+                type: :equity,
+                currency: @config[:default_currency] || 'USD',
+                opening_balance: equity_balance,
+                parent: parent_account
+              )
+              @accounts[:equity] = equity_account
+            end
+          else
+            # Create default equity account with calculated balance
+            equity_account = Account.new(
+              :equity,
+              type: :equity,
+              currency: @config[:default_currency] || 'USD',
+              opening_balance: equity_balance
+            )
+            @accounts[:equity] = equity_account
+          end
+          
+          # Map to equity category if it exists
+          if has_equity_category
+            @category_accounts[has_equity_category] = equity_account unless @category_accounts[has_equity_category]
+            var_data = {
+              name: :equity,
+              type: :financial,
+              frequency: :annual,
+              currency: equity_account.currency,
+              account: :equity,
+              description: "Equity"
+            }
+            has_equity_category.variables << var_data unless has_equity_category.variables.any? { |v| v[:name] == :equity }
+          end
+        end
+      end
+      
+      def find_category_by_type(type)
+        # Recursively search for category with given type
+        @categories.each do |category|
+          found = find_category_by_type_recursive(category, type)
+          return found if found
+        end
+        nil
+      end
+      
+      def find_category_by_type_recursive(category, type)
+        return category if category.type == type
+        
+        category.children.each do |child|
+          found = find_category_by_type_recursive(child, type)
+          return found if found
+        end
+        
+        nil
+      end
+      
+      def validate_category_variables!
+        # Validate that ALL variables in income/expense categories have account mappings
+        @categories.each do |category|
+          validate_category_variables_recursive(category)
+        end
+      end
+      
+      def validate_category_variables_recursive(category)
+        # Skip driver categories
+        return if category.type == :driver
+        
+        # Check variables in this category
+        category.variables.each do |var_data|
+          # Variables in income/expense categories that generate transactions must have accounts
+          # This includes:
+          # - Calculated variables (always need accounts for transactions)
+          # - Expense variables with periodic frequency (quarterly, monthly) that generate transactions
+          # - Income variables: only calculated variables need accounts (regular income vars might be calculation-only)
+          # Annual frequency variables might be calculation-only totals, so we don't require accounts for them
+          if [:income, :expense].include?(category.type)
+            # Check if this variable is meant to generate transactions
+            # For expenses: calculated variables and periodic frequency (quarterly, monthly) need accounts
+            # For income: only calculated variables need accounts (regular income vars might be calculation-only)
+            needs_account = if category.type == :expense
+              var_data[:type] == :calculated || [:quarterly, :monthly, :weekly, :daily].include?(var_data[:frequency])
+            else # income
+              var_data[:type] == :calculated
+            end
+            
+            if needs_account
+              # Must have at least one account specified
+              # For income: credit_account (or account which becomes credit_account)
+              # For expense: debit_account (or account which becomes debit_account)
+              # The other side will be determined automatically by transaction generator
+              has_account = (var_data[:debit_account] || var_data[:credit_account] || var_data[:account])
+              unless has_account
+                var_type_label = var_data[:type] == :calculated ? "Calculated variable" : "Variable"
+                frequency_info = var_data[:frequency] ? " (frequency: #{var_data[:frequency]})" : ""
+                raise ArgumentError.new(
+                  "#{var_type_label} '#{var_data[:name]}' in #{category.type} category#{frequency_info} " \
+                  "must specify an account to generate transactions. Use 'account:', 'debit_account:', or 'credit_account:' " \
+                  "when defining the variable."
+                )
+              end
+              
+              # Auto-create accounts if they don't exist (for income/expense categories)
+              if var_data[:debit_account]
+                var_data[:debit_account] = ensure_account_exists(var_data[:debit_account], category.type)
+              end
+              if var_data[:credit_account]
+                var_data[:credit_account] = ensure_account_exists(var_data[:credit_account], category.type)
+              end
+              if var_data[:account]
+                var_data[:account] = ensure_account_exists(var_data[:account], category.type)
+              end
+            end
+          end
+        end
+        
+        # Recursively check subcategories
+        category.children.each do |child|
+          validate_category_variables_recursive(child)
+        end
+      end
+
+      # Helper to check config values
+      def with_bonus?
+        @config[:with_bonus] == true
+      end
+
+      # Ensure account exists, creating it if necessary
+      # Supports array notation for nested accounts (e.g., [:assets, :checking] or [:liabilities, :accounts_payable])
+      # account_ref: Symbol or Array representing the account
+      # category_type: The type of category (:income, :expense, etc.) to determine default account type
+      def ensure_account_exists(account_ref, category_type)
+        # Extract actual account name and determine account type
+        if account_ref.is_a?(Array)
+          # Validate hierarchy: first element must be a top-level category of type :asset, :liability, or :equity
+          top_level_category_name = account_ref.first.to_sym
+          top_level_category = @categories.find { |c| c.name == top_level_category_name && c.parent.nil? }
+          
+          unless top_level_category && [:asset, :liability, :equity].include?(top_level_category.type)
+            raise ArgumentError, "Account hierarchy must start with a top-level category of type :asset, :liability, or :equity. Got: #{top_level_category_name}"
+          end
+          
+          # Extract account name (last element) and determine type from category
+          actual_account_name = account_ref.last.to_sym
+          account_type = top_level_category.type
+        else
+          # Symbol notation: default to :asset for income/expense variables
+          actual_account_name = account_ref.to_sym
+          account_type = :asset # Default for income/expense categories
+        end
+        
+        # Check if account already exists
+        return actual_account_name if @accounts.key?(actual_account_name)
+        
+        # Create the account
+        new_account = Account.new(
+          actual_account_name,
+          type: account_type,
+          currency: @config[:default_currency] || 'USD',
+          opening_balance: 0,
+          opening_balance_credit_account: :equity
+        )
+        
+        @accounts[actual_account_name] = new_account
+        
+        # Add account to appropriate category
+        ensure_account_in_category(actual_account_name, account_type, account_ref)
+        
+        actual_account_name
+      end
+      
+      # Ensure account is added to appropriate category
+      # account_name: Symbol name of the account
+      # account_type: Type of account (:asset, :liability, :equity)
+      # account_hierarchy: Original account reference (Symbol or Array)
+      def ensure_account_in_category(account_name, account_type, account_hierarchy)
+        target_category = nil
+        
+        if account_hierarchy.is_a?(Array)
+          # Array hierarchy: find or create categories along the path
+          # e.g., [:assets, :checking] -> find/create :assets category, add :checking to it
+          category_path = account_hierarchy[0..-2] # All elements except the last (account name)
+          
+          if category_path.empty?
+            # Just [account_name] - create top-level category
+            category_name = account_type == :asset ? :assets : (account_type == :liability ? :liabilities : :equity)
+            target_category = find_or_create_category(category_name, account_type)
+          else
+            # Navigate/create category path
+            current_parent = nil
+            category_path.each_with_index do |cat_name, idx|
+              cat_name = cat_name.to_sym
+              # Find or create this category
+              if current_parent.nil?
+                # Top-level category
+                target_category = find_or_create_category(cat_name, account_type, parent: nil)
+              else
+                # Subcategory
+                target_category = find_or_create_category(cat_name, account_type, parent: current_parent)
+              end
+              current_parent = target_category
+            end
+          end
+        else
+          # Symbol notation: find or create default top-level category
+          category_name = case account_type
+          when :asset
+            :assets
+          when :liability
+            :liabilities
+          when :equity
+            :equity
+          else
+            :assets # Default fallback
+          end
+          target_category = find_or_create_category(category_name, account_type)
+        end
+        
+        # Check if account is already in this category
+        return if target_category.variables.any? { |v| v[:name] == account_name }
+        
+        # Add account as a variable to the category
+        account = @accounts[account_name]
+        var_data = {
+          name: account_name,
+          type: :financial,
+          frequency: :annual,
+          currency: account.currency,
+          account: account_name,
+          description: account.name.to_s.humanize
+        }
+        target_category.variables << var_data
+      end
+      
+      # Find or create a category
+      def find_or_create_category(name, type, parent: nil)
+        name = name.to_sym
+        
+        # Try to find existing category
+        if parent.nil?
+          # Top-level category
+          category = @categories.find { |c| c.name == name && c.parent.nil? }
+        else
+          # Subcategory
+          category = parent.children.find { |c| c.name == name }
+        end
+        
+        # Create if not found
+        unless category
+          category = Categories::Category.new(name, type: type, parent: parent)
+          if parent
+            parent.children << category
+          else
+            @categories << category
+          end
+        end
+        
+        category
+      end
+
+      # Get or create account for a category
+      # Returns the account associated with the category
+      def get_or_create_category_account(category, parent_account: nil)
+        # Return existing account if already mapped
+        return @category_accounts[category] if @category_accounts[category]
+        
+        # Determine account type from category type
+        account_type = case category.type
+        when :income
+          :income
+        when :expense
+          :expense
+        when :asset
+          :asset
+        when :liability
+          :liability
+        when :equity
+          :equity
+        else
+          raise ArgumentError, "Cannot create account for category type: #{category.type}"
+        end
+        
+        # Check if account already exists by name
+        account_name = category.name.to_sym
+        if @accounts.key?(account_name)
+          account = @accounts[account_name]
+          # Update parent if needed
+          if parent_account && account.parent != parent_account
+            account.instance_variable_set(:@parent, parent_account)
+            parent_account.children << account unless parent_account.children.include?(account)
+          end
+          @category_accounts[category] = account
+          return account
+        end
+        
+        # Create new account for category
+        account = Account.new(
+          account_name,
+          type: account_type,
+          currency: @config[:default_currency] || 'USD',
+          opening_balance: 0,
+          opening_balance_credit_account: :equity,
+          parent: parent_account
+        )
+        
+        @accounts[account_name] = account
+        @category_accounts[category] = account
+        
+        account
+      end
+
+      # Create account for a variable as sub-account of parent account
+      def create_variable_account(variable_name, account_type, parent_account, currency)
+        account_name = variable_name.to_sym
+        
+        # Check if account already exists
+        if @accounts.key?(account_name)
+          account = @accounts[account_name]
+          # Update parent if needed
+          if account.parent != parent_account
+            account.instance_variable_set(:@parent, parent_account)
+            parent_account.children << account unless parent_account.children.include?(account)
+          end
+          return account
+        end
+        
+        # Create new account for variable
+        account = Account.new(
+          account_name,
+          type: account_type,
+          currency: currency || @config[:default_currency] || 'USD',
+          opening_balance: 0,
+          opening_balance_credit_account: :equity,
+          parent: parent_account
+        )
+        
+        @accounts[account_name] = account
+        
+        account
+      end
+
+      # Find default asset account or create one
+      def find_default_asset_account
+        asset_account = @accounts.values.find { |acc| acc.type == :asset }
+        return asset_account.name if asset_account
+        
+        # Create default asset account
+        default_account = Account.new(
+          :default_asset,
+          type: :asset,
+          currency: @config[:default_currency] || 'USD',
+          opening_balance: 0
+        )
+        @accounts[:default_asset] = default_account
+        :default_asset
+      end
+
+      # Find equity account or return :equity
+      def find_equity_account
+        equity_account = @accounts.values.find { |acc| acc.name == :equity && acc.type == :equity }
+        equity_account ? equity_account.name : :equity
+      end
+    end
+  end
+end
+