fin_it 0.1.0

data/lib/fin_it/reports/balance_sheet.rb

@@ -0,0 +1,638 @@
+# frozen_string_literal: true
+
+require_relative 'base_report'
+
+module FinIt
+  module Reports
+    # Error raised when balance sheet doesn't balance
+    class BalanceSheetError < StandardError; end
+    
+    class BalanceSheet < BaseReport
+      # Include asset, liability, and equity categories
+      def included_category_types
+        [:asset, :liability, :equity]
+      end
+      
+      def generate
+        data = super
+        data[:statement_comments] = statement_comments
+        
+        # Validate balance sheet equation: Assets = Liabilities + Equity
+        validate_balance_sheet_equation(data)
+        
+        data
+      end
+      
+      def build_sections
+        sections = {}
+        
+        # Assets section
+        asset_categories = relevant_categories.select { |c| c.type == :asset }
+        sections[:assets] = build_asset_section(asset_categories)
+        
+        # Liabilities section
+        liability_categories = relevant_categories.select { |c| c.type == :liability }
+        sections[:liabilities] = build_liability_section(liability_categories)
+        
+        # Equity section (only actual equity accounts/categories, not net income)
+        equity_categories = relevant_categories.select { |c| c.type == :equity }
+        sections[:equity] = build_category_section(equity_categories, "Equity")
+        sections[:equity][:items] ||= []
+        
+        # If no equity categories but equity accounts exist, show them directly
+        # For equity, use opening balance (not dynamic balance) because:
+        # 1. Equity opening balance is already calculated as Assets - Liabilities
+        # 2. Opening balance transactions would double-count otherwise
+        if equity_categories.empty?
+          # Calculate total equity from opening balances (already balanced: Assets - Liabilities)
+          opening_equity_balance = calculate_opening_equity_balance
+
+          if opening_equity_balance != 0
+            equity_item = {
+              name: :equity,
+              display_name: "Owner's Equity",
+              value: opening_equity_balance,
+              indent: 0,
+              variables: [],
+              description: "Total equity (Assets - Liabilities)",
+              original_name: :equity
+            }
+            sections[:equity][:items] << equity_item
+            sections[:equity][:total] = opening_equity_balance
+          end
+        end
+        
+        # Calculate accumulated net income from model start date to end date
+        # This represents cumulative net income from when the model began
+        # We use model start date (not year start) because:
+        # 1. Asset balances are cumulative from model start
+        # 2. Opening equity is set at model start
+        # 3. This ensures Assets = Liabilities + Opening Equity + Accumulated Net Income
+        accumulation_start = @model.start_date
+        
+        accumulated_net_income = @model.period_net_income(accumulation_start, @end_date, 
+          output_currency: @output_currency, filters: @filters)
+        
+        # Create separate section for accumulated net income
+        sections[:accumulated_net_income] = {
+          name: "Accumulated Net Income",
+          items: [{
+            name: :accumulated_net_income,
+            display_name: "Accumulated Net Income (Period)",
+            value: accumulated_net_income,
+            indent: 0,
+            variables: [],
+            description: "Cumulative net income from model start (Income - Expenses)",
+            original_name: :accumulated_net_income
+          }],
+          total: accumulated_net_income,
+          formula: "income - expenses"
+        }
+        
+        # Also store period net income for validation (just this period, not accumulated)
+        period_net_income = @model.period_net_income(@start_date, @end_date, 
+          output_currency: @output_currency, filters: @filters)
+        
+        # Calculate totals
+        total_assets = sections[:assets][:total] || 0
+        total_liabilities = sections[:liabilities][:total] || 0
+        
+        sections[:total_assets] = {
+          label: "Total Assets",
+          formula: "current_assets + fixed_assets",
+          value: total_assets,
+          total: total_assets
+        }
+        
+        sections[:total_liabilities] = {
+          label: "Total Liabilities",
+          formula: "current_liabilities + long_term_liabilities",
+          value: total_liabilities,
+          total: total_liabilities
+        }
+        
+        # Calculate equity total (equity accounts only, not net income)
+        equity_total = sections[:equity][:total] || 0
+        accumulated_net_income_total = sections[:accumulated_net_income][:total] || 0
+
+        # The balance sheet equation: Assets = Liabilities + Equity + Accumulated Net Income
+        # This should always balance because:
+        # 1. Opening equity = Opening Assets - Opening Liabilities
+        # 2. Accumulated net income = Income transactions - Expense transactions
+        # 3. Asset account balances include opening balances + income credits - expense debits
+        sections[:equity][:total] = equity_total
+
+        total_equity_and_net_income = equity_total + accumulated_net_income_total
+        sections[:total_liabilities_and_equity] = {
+          label: "Total Liabilities and Equity",
+          formula: "total_liabilities + total_equity + accumulated_net_income",
+          value: total_liabilities + total_equity_and_net_income,
+          total: total_liabilities + total_equity_and_net_income
+        }
+        
+        # Store period net income for validation and reporting (just this period, not accumulated)
+        sections[:period_net_income] = {
+          label: "Period Net Income",
+          formula: "income - expenses",
+          value: period_net_income,
+          total: period_net_income
+        }
+        
+        sections
+      end
+      
+      def calculate_totals
+        sections = build_sections
+        {
+          assets: sections[:total_assets][:total] || 0,
+          current_assets: sections[:assets][:current_assets] || 0,
+          fixed_assets: sections[:assets][:fixed_assets] || 0,
+          liabilities: sections[:total_liabilities][:total] || 0,
+          current_liabilities: sections[:liabilities][:current_liabilities] || 0,
+          long_term_liabilities: sections[:liabilities][:long_term_liabilities] || 0,
+          equity: sections[:equity][:total] || 0,
+          total_liabilities_and_equity: sections[:total_liabilities_and_equity][:total] || 0
+        }
+      end
+      
+      def statement_comments
+        {
+          # Override this method in specific reports or via configuration
+          # to add explanatory comments for specific categories
+        }
+      end
+      
+      def validate_balance_sheet_equation(data)
+        totals = data[:totals] || {}
+        total_assets = totals[:assets] || 0
+        total_liabilities_and_equity = totals[:total_liabilities_and_equity] || 0
+        
+        # Convert to floats for comparison
+        assets_f = total_assets.is_a?(Money) ? total_assets.to_f : total_assets.to_f
+        liabilities_equity_f = total_liabilities_and_equity.is_a?(Money) ? total_liabilities_and_equity.to_f : total_liabilities_and_equity.to_f
+        
+        # Allow small rounding differences (0.01)
+        # The balance sheet equation: Assets = Liabilities + Equity
+        # Where Equity includes opening equity + period net income (Income - Expenses)
+        # Since we recalculate equity as Assets - Liabilities, this should always balance
+        difference = (assets_f - liabilities_equity_f).abs
+        
+        unless difference <= 0.01
+          period_net_income = calculate_period_net_income
+          net_income_f = period_net_income.is_a?(Money) ? period_net_income.to_f : period_net_income.to_f
+          raise BalanceSheetError.new(
+            "Balance sheet does not balance: Assets (#{assets_f}) != Liabilities + Equity (#{liabilities_equity_f}). " \
+            "Difference: #{difference}. Period Net Income: #{net_income_f}"
+          )
+        end
+      end
+      
+      # Generate monthly balance sheets for a date range
+      def generate_monthly(start_date, end_date)
+        dates = generate_period_dates(start_date, end_date, :monthly)
+        dates.map do |date|
+          month_start = Date.new(date.year, date.month, 1)
+          month_end = Date.new(date.year, date.month, -1)
+          report = self.class.new(
+            @model,
+            start_date: month_start,
+            end_date: month_end,
+            output_currency: @output_currency,
+            filters: @filters
+          )
+          {
+            period: { start: month_start, end: month_end },
+            report: report.generate
+          }
+        end
+      end
+      
+      # Generate yearly balance sheet for a specific year
+      def generate_yearly(year)
+        year_start = Date.new(year, 1, 1)
+        year_end = Date.new(year, 12, 31)
+        report = self.class.new(
+          @model,
+          start_date: year_start,
+          end_date: year_end,
+          output_currency: @output_currency,
+          filters: @filters
+        )
+        {
+          period: { start: year_start, end: year_end },
+          report: report.generate
+        }
+      end
+      
+      # Generate balance sheet for a specific date (snapshot)
+      def generate_at(date)
+        date = parse_date(date)
+        report = self.class.new(
+          @model,
+          start_date: date,
+          end_date: date,
+          output_currency: @output_currency,
+          filters: @filters
+        )
+        {
+          period: { start: date, end: date },
+          report: report.generate
+        }
+      end
+      
+      # Get all periods in the report date range
+      def get_periods(frequency: :monthly)
+        generate_period_dates(@start_date, @end_date, frequency)
+      end
+      
+      # Get value of a specific section at a date
+      def section_value(section_name, date: nil)
+        date ||= @end_date
+        report = self.class.new(
+          @model,
+          start_date: date,
+          end_date: date,
+          output_currency: @output_currency,
+          filters: @filters
+        )
+        report_data = report.generate
+        extract_section_value(report_data, section_name)
+      end
+      
+      # Get count of items in a section
+      def section_count(section_name)
+        report_data = generate
+        count_section_items(report_data, section_name)
+      end
+      
+      private
+      
+      def build_asset_section(categories)
+        items = []
+        current_assets_total = 0
+        fixed_assets_total = 0
+        
+        # Group by top-level categories
+        top_level = categories.select { |c| c.parent.nil? || !relevant_categories.include?(c.parent) }
+        
+        top_level.each do |category|
+          item = build_category_item(category)
+          next unless item
+          items << item
+          
+          # Categorize as current or fixed asset based on category name or metadata
+          if is_current_asset?(category)
+            current_assets_total += item[:value] || 0
+          else
+            fixed_assets_total += item[:value] || 0
+          end
+        end
+        
+        {
+          name: "Assets",
+          items: items,
+          current_assets: current_assets_total,
+          fixed_assets: fixed_assets_total,
+          total: current_assets_total + fixed_assets_total,
+          formula: "current_assets + fixed_assets"
+        }
+      end
+      
+      def build_liability_section(categories)
+        items = []
+        current_liabilities_total = 0
+        long_term_liabilities_total = 0
+        
+        # Group by top-level categories
+        top_level = categories.select { |c| c.parent.nil? || !relevant_categories.include?(c.parent) }
+        
+        top_level.each do |category|
+          item = build_category_item(category)
+          next unless item
+          items << item
+          
+          # Categorize as current or long-term liability based on category name or metadata
+          if is_current_liability?(category)
+            current_liabilities_total += item[:value] || 0
+          else
+            long_term_liabilities_total += item[:value] || 0
+          end
+        end
+        
+        # Always return a section structure, even if empty
+        {
+          name: "Liabilities",
+          items: items,
+          current_liabilities: current_liabilities_total,
+          long_term_liabilities: long_term_liabilities_total,
+          total: current_liabilities_total + long_term_liabilities_total,
+          formula: "current_liabilities + long_term_liabilities"
+        }
+      end
+      
+      def build_category_section(categories, section_name)
+        items = []
+        total = 0
+        
+        # Group by top-level categories
+        top_level = categories.select { |c| c.parent.nil? || !relevant_categories.include?(c.parent) }
+        
+        top_level.each do |category|
+          item = build_category_item(category)
+          next unless item
+          items << item
+          total += item[:value] || 0
+        end
+        
+        # Always return a section structure, even if empty
+        {
+          name: section_name,
+          items: items,
+          total: total,
+          formula: items.any? ? items.map { |i| i[:name] }.join(" + ") : "0"
+        }
+      end
+      
+      def build_category_item(category, indent_level = 0, period_type: :annual)
+        # Balance sheet items are point-in-time snapshots, not period-based flows
+        # Prefer account hierarchy calculation when available
+
+        # Special handling for equity categories:
+        # Equity opening balance is already calculated as Assets - Liabilities
+        # Using dynamic balance would double-count due to opening balance transactions
+        if category.type == :equity
+          equity_balance = calculate_opening_equity_balance
+          return nil if equity_balance == 0
+
+          return {
+            name: category.name,
+            display_name: category.description || humanize_name(category.name),
+            value: equity_balance,
+            indent: indent_level,
+            variables: [],
+            description: "Total equity (Assets - Liabilities)",
+            original_name: category.name,
+            subcategories: []
+          }
+        end
+
+        # Try account-based calculation first (hierarchical accounts)
+        category_account = @model.category_account(category)
+        if category_account
+          # Use account hierarchy to get balance including children
+          value = @model.account_balance_with_children(category_account.name, @end_date, output_currency: @output_currency)
+
+          # Build subcategories from account children
+          subcategories = []
+          if category_account.children.any?
+            category_account.children.each do |child_account|
+              child_value = @model.account_balance_with_children(child_account.name, @end_date, output_currency: @output_currency)
+              next if child_value == 0
+
+              subcategories << {
+                name: child_account.name,
+                display_name: humanize_name(child_account.name),
+                value: child_value,
+                indent: indent_level + 1,
+                variables: [],
+                description: nil,
+                original_name: child_account.name
+              }
+            end
+          end
+
+          # If category account has no balance/children, fall through to variable-based approach
+          # This handles cases where variables reference DIFFERENT accounts (e.g., variable with account: :checking)
+          unless value == 0 && subcategories.empty?
+            return {
+              name: category.name,
+              display_name: category.description || humanize_name(category.name),
+              value: value,
+              indent: indent_level,
+              variables: [],
+              description: category.description,
+              original_name: category.name,
+              subcategories: subcategories
+            }
+          end
+          # Fall through to variable-based approach if category account has no balance
+        end
+        
+        # Fallback to variable-based calculation (backward compatibility)
+        # Filter variables by project if filter is set
+        filtered_variables = filter_variables_by_project(category.variables)
+        return nil if filtered_variables.empty? && category.variables.any?
+        
+        # Check if we should show individual variables
+        relevant_children = category.children.select { |child| 
+          included_category_types.include?(child.type) && matches_filters?(child) && category_has_relevant_variables?(child)
+        }
+        
+        # If category has subcategories, show them; otherwise show individual variables if multiple exist
+        if relevant_children.any?
+          # Has subcategories - show them
+          # Category total should be sum of children category totals (calculated at category level)
+          # Build children items first to get their values
+          child_items = relevant_children.map do |child|
+            build_category_item(child, indent_level + 1, period_type: period_type || :annual)
+          end.compact
+          
+          # Calculate total from children items (sum of their values)
+          value = child_items.sum { |child_item| child_item[:value] || 0 }
+          
+          display_name = category.description || humanize_name(category.name)
+          
+          item = {
+            name: category.name,
+            display_name: display_name,
+            value: value,
+            indent: indent_level,
+            variables: filtered_variables.map { |v| v[:name] },
+            description: category.description,
+            original_name: category.name,
+            subcategories: child_items
+          }
+          
+          item
+        elsif filtered_variables.length > 1
+          # Multiple variables, no subcategories - show each variable separately
+          subcategories = filtered_variables.map do |var|
+            # Balance sheet values are point-in-time snapshots
+            var_value = calculate_variable_value_for_balance_sheet(var)
+            
+            {
+              name: var[:name],
+              display_name: var[:description] || humanize_name(var[:name]),
+              value: var_value,
+              indent: indent_level + 1,
+              variables: [var[:name]],
+              description: var[:description],
+              original_name: var[:name]
+            }
+          end
+          
+          total_value = subcategories.sum { |sub| sub[:value] || 0 }
+          
+          {
+            name: category.name,
+            display_name: category.description || humanize_name(category.name),
+            value: total_value,
+            indent: indent_level,
+            variables: filtered_variables.map { |v| v[:name] },
+            description: category.description,
+            original_name: category.name,
+            subcategories: subcategories
+          }
+        elsif filtered_variables.length == 1
+          # Single variable - show category total with the variable as a subcategory
+          # This ensures individual accounts are always visible in the balance sheet
+          var = filtered_variables.first
+          var_value = calculate_variable_value_for_balance_sheet(var)
+          
+          subcategory = {
+            name: var[:name],
+            display_name: var[:description] || humanize_name(var[:name]),
+            value: var_value,
+            indent: indent_level + 1,
+            variables: [var[:name]],
+            description: var[:description],
+            original_name: var[:name]
+          }
+          
+          # Category total should be the variable value (since it's the only one)
+          value = var_value
+          
+          display_name = category.description || humanize_name(category.name)
+          
+          {
+            name: category.name,
+            display_name: display_name,
+            value: value,
+            indent: indent_level,
+            variables: filtered_variables.map { |v| v[:name] },
+            description: category.description,
+            original_name: category.name,
+            subcategories: [subcategory]
+          }
+        else
+          # No variables - use model's category_total_via_account if available
+          value = @model.category_total_via_account(category, @start_date, @end_date, 
+            period_type: :annual, output_currency: @output_currency, use_balance: true)
+          
+          return nil if value == 0
+          
+          display_name = category.description || humanize_name(category.name)
+          
+          {
+            name: category.name,
+            display_name: display_name,
+            value: value,
+            indent: indent_level,
+            variables: [],
+            description: category.description,
+            original_name: category.name
+          }
+        end
+      end
+      
+      def filter_variables_by_project(variables)
+        return variables unless @filters[:project]
+        
+        variables.select { |var| variable_matches_project?(var, @filters[:project]) }
+      end
+      
+      def calculate_category_total(category, variables)
+        # Use model's category_total_via_account method (prefers account hierarchy)
+        # Balance sheets are point-in-time, so always use annual period type and balance
+        @model.category_total_via_account(
+          category,
+          @start_date,
+          @end_date,
+          period_type: :annual,
+          output_currency: @output_currency,
+          filters: @filters,
+          use_balance: true
+        )
+      end
+      
+      def calculate_variable_value_for_balance_sheet(var)
+        # For balance sheet items, prefer actual account balance over declared variable value
+        # This gives the real balance at the report date, including all transactions
+        account_name = var[:account]
+        if account_name && @model.accounts[account_name]
+          # Generate transactions to ensure balance is up to date
+          @model.generate_transactions(@end_date)
+          balance = @model.account_balance(account_name, as_of_date: @end_date)
+
+          # Convert to output currency if needed
+          account = @model.accounts[account_name]
+          if account.currency != @output_currency
+            balance_money = Money.new((balance * 100).to_i, account.currency)
+            balance = balance_money.exchange_to(@output_currency).to_f
+          end
+
+          balance
+        else
+          # Fallback to model's category_variable_value method
+          @model.category_variable_value(
+            var,
+            @end_date,
+            period_type: :annual,
+            output_currency: @output_currency,
+            category_type: nil
+          )
+        end
+      end
+      
+      def is_current_asset?(category)
+        # Check category name or metadata for current asset indicators
+        name_str = category.name.to_s.downcase
+        name_str.include?('current') || 
+        name_str.include?('cash') || 
+        name_str.include?('checking') || 
+        name_str.include?('savings') ||
+        name_str.include?('receivable') ||
+        category.metadata[:asset_type] == :current
+      end
+      
+      def is_current_liability?(category)
+        # Check category name or metadata for current liability indicators
+        name_str = category.name.to_s.downcase
+        name_str.include?('current') || 
+        name_str.include?('payable') ||
+        name_str.include?('credit_card') ||
+        name_str.include?('short_term') ||
+        category.metadata[:liability_type] == :current
+      end
+      
+      # Calculate opening equity balance
+      # This is the sum of all equity account opening balances.
+      # The equity account opening balance is already calculated as: Assets - Liabilities
+      # So we just need to sum equity account opening balances, not recalculate from assets/liabilities.
+      def calculate_opening_equity_balance
+        # Sum equity account opening balances only
+        # The equity account is auto-created with opening_balance = assets - liabilities
+        equity_accounts = @model.accounts.values.select { |acc| acc.type == :equity }
+        equity_accounts.sum do |account|
+          opening_balance = account.opening_balance.to_f
+          # Convert to output currency if needed
+          if account.currency != @output_currency
+            money = Money.new((opening_balance * 100).to_i, account.currency)
+            money = money.exchange_to(@output_currency)
+            opening_balance = money.to_f
+          end
+          opening_balance
+        end
+      end
+      
+      # Calculate period net income (Income - Expenses) for the report period
+      # Delegates to model's period_net_income method
+      def calculate_period_net_income
+        @model.period_net_income(@start_date, @end_date, 
+          output_currency: @output_currency, filters: @filters)
+      end
+      
+    end
+  end
+end
+