fin_it 0.1.0

data/lib/fin_it/reports/custom_sheet.rb

@@ -0,0 +1,436 @@
+# frozen_string_literal: true
+
+module FinIt
+  module Reports
+    # A customizable report for creating intro/summary sheets
+    # Supports both static content (headers, paragraphs, tables) and
+    # dynamic content (model metrics, account balances, scenario comparisons)
+    #
+    # Usage:
+    #   # Static content only
+    #   intro = FinIt::Reports::CustomSheet.build(title: "Overview") do
+    #     header "Financial Model", level: 1
+    #     paragraph "This report covers fiscal year 2025."
+    #     bullet_list ["Scenario A", "Scenario B"]
+    #     table(headers: ["Metric", "Value"], rows: [["Revenue", "$100k"]])
+    #   end
+    #
+    #   # With dynamic model data
+    #   intro = FinIt::Reports::CustomSheet.build(title: "Summary", model: model) do
+    #     header "Key Metrics", level: 1
+    #     model_metric :net_income, label: "Net Income"
+    #     account_balance :checking, label: "Cash Position"
+    #     metrics_table(metrics: [:net_income, :total_expenses])
+    #   end
+    #
+    class CustomSheet
+      attr_reader :title, :sections, :model, :output_currency
+
+      # Alias for compatibility with BaseOutput
+      alias_method :currency, :output_currency
+
+      def initialize(title:, sections: [], model: nil, output_currency: 'USD')
+        @title = title
+        @sections = sections
+        @model = model
+        @output_currency = output_currency
+      end
+
+      # DSL builder for creating custom sheets
+      def self.build(title:, model: nil, output_currency: 'USD', &block)
+        sheet = new(title: title, model: model, output_currency: output_currency)
+        sheet.instance_eval(&block) if block_given?
+        sheet
+      end
+
+      # --- Static Content DSL ---
+
+      def header(text, level: 1)
+        @sections << { type: :header, text: text, level: level }
+        self
+      end
+
+      def paragraph(text)
+        @sections << { type: :paragraph, text: text }
+        self
+      end
+
+      def spacer(rows: 1)
+        @sections << { type: :spacer, rows: rows }
+        self
+      end
+
+      def key_value(label, value)
+        @sections << { type: :key_value, label: label, value: value }
+        self
+      end
+
+      def bullet_list(items)
+        @sections << { type: :bullet_list, items: items }
+        self
+      end
+
+      def numbered_list(items)
+        @sections << { type: :numbered_list, items: items }
+        self
+      end
+
+      def table(headers:, rows:, title: nil)
+        @sections << { type: :table, headers: headers, rows: rows, title: title }
+        self
+      end
+
+      def horizontal_rule
+        @sections << { type: :hr }
+        self
+      end
+
+      def image(path, alt_text: nil, width: nil, height: nil)
+        @sections << { type: :image, path: path, alt_text: alt_text, width: width, height: height }
+        self
+      end
+
+      def note(text, style: :info)
+        # style can be :info, :warning, :success, :error
+        @sections << { type: :note, text: text, style: style }
+        self
+      end
+
+      # --- Dynamic Content DSL (requires model) ---
+
+      def model_metric(variable, label: nil, start_date: nil, end_date: nil, format: :currency)
+        require_model!("model_metric")
+        @sections << {
+          type: :model_metric,
+          variable: variable,
+          label: label || humanize_name(variable),
+          start_date: start_date,
+          end_date: end_date,
+          format: format
+        }
+        self
+      end
+
+      def account_balance(account_name, label: nil, as_of: nil, format: :currency)
+        require_model!("account_balance")
+        @sections << {
+          type: :account_balance,
+          account: account_name,
+          label: label || humanize_name(account_name),
+          as_of: as_of,
+          format: format
+        }
+        self
+      end
+
+      def metrics_table(metrics:, title: nil, start_date: nil, end_date: nil)
+        require_model!("metrics_table")
+        @sections << {
+          type: :metrics_table,
+          title: title,
+          metrics: metrics,
+          start_date: start_date,
+          end_date: end_date
+        }
+        self
+      end
+
+      def scenario_comparison_summary(scenarios:, metrics:, start_date: nil, end_date: nil, title: nil)
+        require_model!("scenario_comparison_summary")
+        @sections << {
+          type: :scenario_comparison_summary,
+          scenarios: scenarios,
+          metrics: metrics,
+          start_date: start_date,
+          end_date: end_date,
+          title: title
+        }
+        self
+      end
+
+      def period_comparison_summary(periods:, metrics:, title: nil)
+        require_model!("period_comparison_summary")
+        @sections << {
+          type: :period_comparison_summary,
+          periods: periods,
+          metrics: metrics,
+          title: title
+        }
+        self
+      end
+
+      # --- Report Generation ---
+
+      def generate
+        # Resolve dynamic content if model is present
+        resolved_sections = resolve_dynamic_sections
+
+        {
+          report_type: "CustomSheet",
+          title: @title,
+          sections: resolved_sections,
+          currency: @output_currency,
+          generated_at: Time.now
+        }
+      end
+
+      def output(output_class, **options)
+        output_class.new(self, options).generate
+      end
+
+      private
+
+      def require_model!(method_name)
+        raise ArgumentError, "Model required for #{method_name}. Pass model: to CustomSheet.build" unless @model
+      end
+
+      def humanize_name(name)
+        name.to_s.split('_').map(&:capitalize).join(' ')
+      end
+
+      def resolve_dynamic_sections
+        @sections.map do |section|
+          case section[:type]
+          when :model_metric
+            resolve_model_metric(section)
+          when :account_balance
+            resolve_account_balance(section)
+          when :metrics_table
+            resolve_metrics_table(section)
+          when :scenario_comparison_summary
+            resolve_scenario_comparison_summary(section)
+          when :period_comparison_summary
+            resolve_period_comparison_summary(section)
+          else
+            section
+          end
+        end
+      end
+
+      def resolve_model_metric(section)
+        start_date = parse_date(section[:start_date]) if section[:start_date]
+        end_date = parse_date(section[:end_date]) if section[:end_date]
+
+        # Use end_date for calculation, or model's default end
+        calc_date = end_date || Date.today
+
+        # Ensure transactions are generated
+        @model.generate_transactions(calc_date)
+
+        value = calculate_metric(@model, section[:variable], start_date, end_date)
+        formatted_value = format_value(value, section[:format])
+
+        {
+          type: :key_value,
+          label: section[:label],
+          value: formatted_value
+        }
+      end
+
+      def resolve_account_balance(section)
+        as_of = section[:as_of] ? parse_date(section[:as_of]) : Date.today
+
+        @model.generate_transactions(as_of)
+
+        value = @model.account_balance(section[:account], as_of_date: as_of)
+        formatted_value = format_value(value, section[:format])
+
+        {
+          type: :key_value,
+          label: section[:label],
+          value: formatted_value
+        }
+      end
+
+      def resolve_metrics_table(section)
+        start_date = parse_date(section[:start_date]) if section[:start_date]
+        end_date = parse_date(section[:end_date]) if section[:end_date]
+        calc_date = end_date || Date.today
+
+        @model.generate_transactions(calc_date)
+
+        rows = section[:metrics].map do |metric|
+          value = calculate_metric(@model, metric, start_date, end_date)
+          [humanize_name(metric), format_value(value, :currency)]
+        end
+
+        {
+          type: :table,
+          title: section[:title],
+          headers: ["Metric", "Value"],
+          rows: rows
+        }
+      end
+
+      def resolve_scenario_comparison_summary(section)
+        start_date = parse_date(section[:start_date]) if section[:start_date]
+        end_date = parse_date(section[:end_date]) if section[:end_date]
+        calc_date = end_date || Date.today
+
+        @model.generate_transactions(calc_date)
+        section[:scenarios].each_value { |m| m.generate_transactions(calc_date) }
+
+        headers = ["Metric", "Base"] + section[:scenarios].keys.map { |k| humanize_name(k) }
+
+        rows = section[:metrics].map do |metric|
+          base_value = calculate_metric(@model, metric, start_date, end_date)
+          scenario_values = section[:scenarios].values.map do |scenario_model|
+            calculate_metric(scenario_model, metric, start_date, end_date)
+          end
+
+          [humanize_name(metric), format_value(base_value, :currency)] +
+            scenario_values.map { |v| format_value(v, :currency) }
+        end
+
+        {
+          type: :table,
+          title: section[:title] || "Scenario Comparison",
+          headers: headers,
+          rows: rows
+        }
+      end
+
+      def resolve_period_comparison_summary(section)
+        periods = section[:periods].map do |p|
+          {
+            name: p[:name],
+            start_date: parse_date(p[:start_date]),
+            end_date: parse_date(p[:end_date])
+          }
+        end
+
+        # Generate transactions for the latest period
+        last_date = periods.map { |p| p[:end_date] }.max
+        @model.generate_transactions(last_date)
+
+        headers = ["Metric"] + periods.map { |p| p[:name] }
+
+        rows = section[:metrics].map do |metric|
+          period_values = periods.map do |period|
+            calculate_metric(@model, metric, period[:start_date], period[:end_date])
+          end
+
+          [humanize_name(metric)] + period_values.map { |v| format_value(v, :currency) }
+        end
+
+        {
+          type: :table,
+          title: section[:title] || "Period Comparison",
+          headers: headers,
+          rows: rows
+        }
+      end
+
+      def calculate_metric(model, metric, start_date, end_date)
+        case metric
+        when :net_income
+          model.period_net_income(
+            start_date || model.start_date,
+            end_date || Date.today,
+            output_currency: @output_currency
+          )
+        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)
+        else
+          model.calculator.calculate(
+            metric,
+            date: end_date || Date.today,
+            output_currency: @output_currency
+          )
+        end
+      end
+
+      def calculate_total_income(model, start_date, end_date)
+        income_categories = model.categories.select { |c| c.type == :income }
+        income_categories.sum do |category|
+          model.category_total_for_period(
+            category,
+            start_date || model.start_date,
+            end_date || Date.today,
+            period_type: :annual,
+            output_currency: @output_currency
+          ).abs
+        end
+      end
+
+      def calculate_total_expenses(model, start_date, end_date)
+        expense_categories = model.categories.select { |c| c.type == :expense }
+        expense_categories.sum do |category|
+          model.category_total_for_period(
+            category,
+            start_date || model.start_date,
+            end_date || Date.today,
+            period_type: :annual,
+            output_currency: @output_currency
+          ).abs
+        end
+      end
+
+      def calculate_ending_cash(model, end_date)
+        cash_accounts = model.accounts.values.select do |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        end
+
+        cash_accounts.sum do |account|
+          model.account_balance(account.name, as_of_date: end_date || Date.today)
+        end
+      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 format_value(value, format)
+        case format
+        when :currency
+          if value.is_a?(Money)
+            "$#{format_number(value.to_f)}"
+          else
+            "$#{format_number(value.to_f)}"
+          end
+        when :number
+          format_number(value.to_f)
+        when :percentage
+          "#{(value.to_f * 100).round(2)}%"
+        else
+          value.to_s
+        end
+      end
+
+      def format_number(num)
+        # Format with thousands separator and 2 decimal places
+        parts = ('%.2f' % num).split('.')
+        parts[0].gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, '\\1,')
+        parts.join('.')
+      end
+
+      def parse_date(date)
+        return date if date.is_a?(Date)
+        return nil if date.nil?
+
+        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