fin_it 0.1.0

data/lib/fin_it/reports/period_comparison.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module FinIt
+  module Reports
+    # Report for comparing metrics across multiple time periods within the same model
+    # Useful for Q1 vs Q2 vs Q3 vs Q4 comparisons, year-over-year, etc.
+    #
+    # Usage:
+    #   comparison = FinIt::Reports::PeriodComparison.new(
+    #     model,
+    #     periods: [
+    #       { name: "Q1 2025", start_date: "2025-01-01", end_date: "2025-03-31" },
+    #       { name: "Q2 2025", start_date: "2025-04-01", end_date: "2025-06-30" },
+    #       { name: "Q3 2025", start_date: "2025-07-01", end_date: "2025-09-30" },
+    #       { name: "Q4 2025", start_date: "2025-10-01", end_date: "2025-12-31" }
+    #     ],
+    #     metrics: [:net_income, :total_revenue, :total_expenses],
+    #     output_currency: 'USD'
+    #   )
+    #
+    class PeriodComparison
+      attr_reader :model, :periods, :metrics, :output_currency
+
+      # Alias for compatibility
+      alias_method :currency, :output_currency
+
+      BUILT_IN_METRICS = [:net_income, :total_revenue, :total_income, :total_expenses,
+                          :ending_cash, :beginning_cash, :gross_profit, :operating_income].freeze
+
+      def initialize(model, periods:, metrics:, output_currency: 'USD')
+        @model = model
+        @periods = normalize_periods(periods)
+        @metrics = metrics
+        @output_currency = output_currency
+        @normalized_metrics = normalize_metrics
+      end
+
+      def generate
+        # Generate transactions up to the last period end date
+        last_end_date = @periods.map { |p| p[:end_date] }.max
+        @model.generate_transactions(last_end_date)
+
+        {
+          report_type: "PeriodComparison",
+          metadata: build_metadata,
+          periods: calculate_all_periods,
+          variances: calculate_period_variances
+        }
+      end
+
+      def output(output_class, **options)
+        output_class.new(self, options).generate
+      end
+
+      # Get normalized metric configs for external use
+      def normalized_metrics
+        @normalized_metrics
+      end
+
+      private
+
+      def normalize_periods(periods)
+        periods.map do |p|
+          {
+            name: p[:name],
+            start_date: parse_date(p[:start_date]),
+            end_date: parse_date(p[:end_date])
+          }
+        end
+      end
+
+      def normalize_metrics
+        @metrics.map do |metric|
+          case metric
+          when Symbol
+            {
+              variable: metric,
+              label: humanize_name(metric),
+              format: :currency
+            }
+          when Hash
+            var = metric[:variable]
+            raise ArgumentError, "Metric hash requires :variable key" unless var
+
+            {
+              variable: var,
+              label: metric[:label] || humanize_name(var),
+              format: metric[:format] || :currency
+            }
+          else
+            raise ArgumentError, "Invalid metric: #{metric.inspect}. Must be Symbol or Hash."
+          end
+        end
+      end
+
+      def humanize_name(name)
+        name.to_s.split('_').map(&:capitalize).join(' ')
+      end
+
+      def build_metadata
+        {
+          report_type: "PeriodComparison",
+          periods: @periods,
+          metrics: @metrics,
+          normalized_metrics: @normalized_metrics,
+          currency: @output_currency,
+          generated_at: Time.now
+        }
+      end
+
+      def calculate_all_periods
+        @periods.map do |period|
+          {
+            name: period[:name],
+            start_date: period[:start_date],
+            end_date: period[:end_date],
+            metrics: calculate_metrics_for_period(period)
+          }
+        end
+      end
+
+      def calculate_metrics_for_period(period)
+        result = {}
+        @normalized_metrics.each do |metric_config|
+          key = metric_config[:variable]
+          result[key] = calculate_single_metric(metric_config, period)
+        end
+        result
+      end
+
+      def calculate_single_metric(metric_config, period)
+        var_name = metric_config[:variable]
+        start_date = period[:start_date]
+        end_date = period[:end_date]
+
+        case var_name
+        when :net_income
+          value = @model.period_net_income(start_date, end_date, output_currency: @output_currency)
+          value.is_a?(Money) ? value.to_f : value.to_f
+        when :total_revenue, :total_income
+          calculate_total_income(start_date, end_date)
+        when :total_expenses
+          calculate_total_expenses(start_date, end_date)
+        when :ending_cash
+          calculate_ending_cash(end_date)
+        when :beginning_cash
+          calculate_beginning_cash(start_date)
+        when :gross_profit
+          calculate_gross_profit(start_date, end_date)
+        when :operating_income
+          calculate_operating_income(start_date, end_date)
+        else
+          # Custom variable
+          value = @model.calculator.calculate(
+            var_name,
+            date: end_date,
+            output_currency: @output_currency,
+            period_type: :annual
+          )
+          value.is_a?(Money) ? value.to_f : value.to_f
+        end
+      end
+
+      def calculate_total_income(start_date, end_date)
+        income_categories = @model.categories.select { |c| c.type == :income }
+        total = income_categories.sum do |category|
+          @model.category_total_for_period(
+            category,
+            start_date,
+            end_date,
+            period_type: :annual,
+            output_currency: @output_currency
+          ).abs
+        end
+        total.is_a?(Money) ? total.to_f : total.to_f
+      end
+
+      def calculate_total_expenses(start_date, end_date)
+        expense_categories = @model.categories.select { |c| c.type == :expense }
+        total = expense_categories.sum do |category|
+          @model.category_total_for_period(
+            category,
+            start_date,
+            end_date,
+            period_type: :annual,
+            output_currency: @output_currency
+          ).abs
+        end
+        total.is_a?(Money) ? total.to_f : total.to_f
+      end
+
+      def calculate_ending_cash(end_date)
+        cash_accounts = @model.accounts.values.select do |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        end
+
+        total = cash_accounts.sum do |account|
+          @model.account_balance(account.name, as_of_date: end_date)
+        end
+
+        total.is_a?(Money) ? total.to_f : total.to_f
+      end
+
+      def calculate_beginning_cash(start_date)
+        cash_accounts = @model.accounts.values.select do |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        end
+
+        previous_date = start_date - 1
+
+        if previous_date < @model.start_date
+          cash_accounts.sum { |acc| acc.opening_balance.to_f }
+        else
+          cash_accounts.sum do |account|
+            @model.account_balance(account.name, as_of_date: previous_date)
+          end
+        end
+      end
+
+      def calculate_gross_profit(start_date, end_date)
+        total_income = calculate_total_income(start_date, end_date)
+
+        cogs_categories = @model.categories.select do |c|
+          c.type == :expense &&
+          (c.name.to_s.include?('cogs') || c.name.to_s.include?('cost_of_goods'))
+        end
+
+        total_cogs = cogs_categories.sum do |category|
+          @model.category_total_for_period(
+            category, start_date, end_date,
+            period_type: :annual, output_currency: @output_currency
+          ).abs
+        end
+
+        total_income - (total_cogs.is_a?(Money) ? total_cogs.to_f : total_cogs.to_f)
+      end
+
+      def calculate_operating_income(start_date, end_date)
+        calculate_gross_profit(start_date, end_date) - calculate_total_expenses(start_date, end_date)
+      end
+
+      def is_cash_account?(account)
+        name = account.name.to_s.downcase
+        cash_patterns = ['cash', 'checking', 'savings', 'bank', 'money_market']
+        cash_patterns.any? { |pattern| name.include?(pattern) }
+      end
+
+      def calculate_period_variances
+        # Compare each period to the previous period
+        results = []
+
+        @periods.each_with_index do |period, idx|
+          if idx == 0
+            # First period has no comparison
+            results << {
+              name: period[:name],
+              variances: nil
+            }
+          else
+            prev_period = @periods[idx - 1]
+            prev_metrics = calculate_metrics_for_period(prev_period)
+            curr_metrics = calculate_metrics_for_period(period)
+
+            variances = {}
+            @normalized_metrics.each do |metric_config|
+              key = metric_config[:variable]
+              prev_val = prev_metrics[key] || 0
+              curr_val = curr_metrics[key] || 0
+
+              variances[key] = {
+                absolute: curr_val - prev_val,
+                percentage: prev_val != 0 ?
+                  ((curr_val - prev_val) / prev_val.to_f * 100).round(2) : 0.0
+              }
+            end
+
+            results << {
+              name: period[:name],
+              variances: variances
+            }
+          end
+        end
+
+        results
+      end
+
+      def parse_date(date)
+        return date if date.is_a?(Date)
+
+        case date
+        when String
+          if date =~ /^\d{4}$/
+            Date.new(date.to_i, 1, 1)
+          elsif date =~ /^\d{4}-\d{2}$/
+            Date.parse("#{date}-01")
+          else
+            Date.parse(date)
+          end
+        when Integer
+          Date.new(date, 1, 1)
+        when Time
+          date.to_date
+        else
+          raise ArgumentError, "Cannot parse date: #{date}"
+        end
+      end
+    end
+  end
+end

data/lib/fin_it/reports/scenario_comparison.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module FinIt
+  module Reports
+    # Report for comparing base model vs one or more scenario models
+    # Supports both simple symbol metrics and hash-based metric configurations:
+    #
+    # Simple: :net_income, :total_expenses
+    # Hash:   { variable: :revenue, period_type: :monthly, label: "Monthly Revenue" }
+    #
+    class ScenarioComparison
+      attr_reader :base_model, :scenarios, :start_date, :end_date, :output_currency, :metrics
+
+      # Alias for compatibility with BaseOutput
+      alias_method :currency, :output_currency
+
+      DEFAULT_METRICS = [:net_income, :total_revenue, :total_expenses, :ending_cash].freeze
+      BUILT_IN_METRICS = [:net_income, :total_revenue, :total_income, :total_expenses,
+                          :ending_cash, :beginning_cash, :gross_profit, :operating_income].freeze
+
+      def initialize(base_model, scenarios:, start_date:, end_date:,
+                     output_currency: 'USD', metrics: DEFAULT_METRICS)
+        @base_model = base_model
+        @scenarios = scenarios  # Hash of { name: model }
+        @start_date = parse_date(start_date)
+        @end_date = parse_date(end_date)
+        @output_currency = output_currency
+        @metrics = metrics
+        @normalized_metrics = normalize_metrics
+      end
+
+      def generate
+        # Ensure transactions are generated for all models
+        @base_model.generate_transactions(@end_date)
+        @scenarios.each_value { |model| model.generate_transactions(@end_date) }
+
+        base_metrics = calculate_metrics(@base_model)
+
+        {
+          report_type: "ScenarioComparison",
+          metadata: build_metadata,
+          base: base_metrics,
+          scenarios: @scenarios.transform_values { |model| calculate_metrics(model) },
+          variances: calculate_variances(base_metrics)
+        }
+      end
+
+      # Get normalized metric configs for external use (e.g., outputs)
+      def normalized_metrics
+        @normalized_metrics
+      end
+
+      # Output to a specific output class
+      def output(output_class, **options)
+        output_class.new(self, options).generate
+      end
+
+      private
+
+      # Normalize metrics to a consistent hash format
+      # Supports both simple symbols and hash configurations
+      def normalize_metrics
+        @metrics.map do |metric|
+          case metric
+          when Symbol
+            {
+              variable: metric,
+              period_type: :annual,
+              start_date: @start_date,
+              end_date: @end_date,
+              label: humanize_name(metric),
+              format: :currency,
+              key: metric  # Key used in result hash
+            }
+          when Hash
+            var = metric[:variable]
+            raise ArgumentError, "Metric hash requires :variable key" unless var
+
+            # Generate key: use explicit :key, or build from variable + period_name, or just variable
+            key = if metric[:key]
+                    metric[:key]
+                  elsif metric[:period_name]
+                    :"#{var}_#{metric[:period_name].downcase.gsub(' ', '_')}"
+                  else
+                    var
+                  end
+
+            {
+              variable: var,
+              period_type: metric[:period_type] || :annual,
+              start_date: metric[:start_date] ? parse_date(metric[:start_date]) : @start_date,
+              end_date: metric[:end_date] ? parse_date(metric[:end_date]) : @end_date,
+              label: metric[:label] || (metric[:period_name] ? "#{humanize_name(var)} (#{metric[:period_name]})" : humanize_name(var)),
+              format: metric[:format] || :currency,
+              key: key
+            }
+          else
+            raise ArgumentError, "Invalid metric: #{metric.inspect}. Must be Symbol or Hash."
+          end
+        end
+      end
+
+      def humanize_name(name)
+        name.to_s.split('_').map(&:capitalize).join(' ')
+      end
+
+      def build_metadata
+        {
+          report_type: "ScenarioComparison",
+          start_date: @start_date,
+          end_date: @end_date,
+          currency: @output_currency,
+          base_model_name: "Base",
+          scenario_names: @scenarios.keys,
+          metrics: @metrics,
+          normalized_metrics: @normalized_metrics,
+          generated_at: Time.now
+        }
+      end
+
+      def calculate_metrics(model)
+        result = {}
+
+        @normalized_metrics.each do |metric_config|
+          key = metric_config[:key]
+          result[key] = calculate_single_metric(model, metric_config)
+        end
+
+        result
+      end
+
+      def calculate_single_metric(model, metric_config)
+        var_name = metric_config[:variable]
+        start_date = metric_config[:start_date]
+        end_date = metric_config[:end_date]
+        period_type = metric_config[:period_type]
+
+        case var_name
+        when :net_income
+          value = model.period_net_income(start_date, end_date, output_currency: @output_currency)
+          value.is_a?(Money) ? value.to_f : value.to_f
+        when :total_revenue, :total_income
+          calculate_total_income(model, start_date, end_date)
+        when :total_expenses
+          calculate_total_expenses(model, start_date, end_date)
+        when :ending_cash
+          calculate_ending_cash(model, end_date)
+        when :beginning_cash
+          calculate_beginning_cash(model, start_date)
+        when :gross_profit
+          calculate_gross_profit(model, start_date, end_date)
+        when :operating_income
+          calculate_operating_income(model, start_date, end_date)
+        else
+          # Custom variable - use period_type
+          value = model.calculator.calculate(
+            var_name,
+            date: end_date,
+            output_currency: @output_currency,
+            period_type: period_type
+          )
+          value.is_a?(Money) ? value.to_f : value.to_f
+        end
+      end
+
+      def calculate_total_income(model, start_date, end_date)
+        income_categories = model.categories.select { |c| c.type == :income }
+        total = income_categories.sum do |category|
+          model.category_total_for_period(
+            category,
+            start_date,
+            end_date,
+            period_type: :annual,
+            output_currency: @output_currency
+          ).abs
+        end
+        total.is_a?(Money) ? total.to_f : total.to_f
+      end
+
+      def calculate_total_expenses(model, start_date, end_date)
+        expense_categories = model.categories.select { |c| c.type == :expense }
+        total = expense_categories.sum do |category|
+          model.category_total_for_period(
+            category,
+            start_date,
+            end_date,
+            period_type: :annual,
+            output_currency: @output_currency
+          ).abs
+        end
+        total.is_a?(Money) ? total.to_f : total.to_f
+      end
+
+      def calculate_ending_cash(model, end_date)
+        # Find cash accounts (checking, savings, etc.)
+        cash_accounts = model.accounts.values.select do |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        end
+
+        total = cash_accounts.sum do |account|
+          model.account_balance(account.name, as_of_date: end_date)
+        end
+
+        total.is_a?(Money) ? total.to_f : total.to_f
+      end
+
+      def calculate_beginning_cash(model, start_date)
+        cash_accounts = model.accounts.values.select do |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        end
+
+        previous_date = start_date - 1
+
+        if previous_date < model.start_date
+          cash_accounts.sum { |acc| acc.opening_balance.to_f }
+        else
+          cash_accounts.sum do |account|
+            model.account_balance(account.name, as_of_date: previous_date)
+          end
+        end
+      end
+
+      def calculate_gross_profit(model, start_date, end_date)
+        # Gross profit = Revenue - COGS
+        # Look for expense categories with 'cogs' or 'cost_of_goods' in name
+        total_income = calculate_total_income(model, start_date, end_date)
+
+        cogs_categories = model.categories.select do |c|
+          c.type == :expense &&
+          (c.name.to_s.include?('cogs') || c.name.to_s.include?('cost_of_goods'))
+        end
+
+        total_cogs = cogs_categories.sum do |category|
+          model.category_total_for_period(
+            category, start_date, end_date,
+            period_type: :annual, output_currency: @output_currency
+          ).abs
+        end
+
+        total_income - (total_cogs.is_a?(Money) ? total_cogs.to_f : total_cogs.to_f)
+      end
+
+      def calculate_operating_income(model, start_date, end_date)
+        # Operating income = Gross Profit - Operating Expenses
+        calculate_gross_profit(model, start_date, end_date) - calculate_total_expenses(model, start_date, end_date)
+      end
+
+      def is_cash_account?(account)
+        name = account.name.to_s.downcase
+        cash_patterns = ['cash', 'checking', 'savings', 'bank', 'money_market']
+        cash_patterns.any? { |pattern| name.include?(pattern) }
+      end
+
+      def calculate_variances(base_metrics)
+        @scenarios.transform_values do |model|
+          scenario_metrics = calculate_metrics(model)
+
+          result = {}
+          @normalized_metrics.each do |metric_config|
+            key = metric_config[:key]
+            base_value = base_metrics[key] || 0
+            scenario_value = scenario_metrics[key] || 0
+
+            result[key] = {
+              absolute: scenario_value - base_value,
+              percentage: base_value != 0 ?
+                ((scenario_value - base_value) / base_value.to_f * 100).round(2) : 0.0
+            }
+          end
+          result
+        end
+      end
+
+      def parse_date(date)
+        return date if date.is_a?(Date)
+
+        case date
+        when String
+          if date =~ /^\d{4}$/
+            Date.new(date.to_i, 1, 1)
+          elsif date =~ /^\d{4}-\d{2}$/
+            Date.parse("#{date}-01")
+          else
+            Date.parse(date)
+          end
+        when Integer
+          Date.new(date, 1, 1)
+        when Time
+          date.to_date
+        else
+          raise ArgumentError, "Cannot parse date: #{date}"
+        end
+      end
+    end
+  end
+end