fin_it 0.1.0

data/lib/fin_it/reports/base_report.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module FinIt
+  module Reports
+    class BaseReport
+      attr_reader :model, :start_date, :end_date, :output_currency, :filters
+      
+      def initialize(model, start_date:, end_date:, output_currency: 'USD', filters: {})
+        @model = model
+        @start_date = start_date
+        @end_date = end_date
+        @output_currency = output_currency
+        @filters = filters
+      end
+      
+      # Abstract method - subclasses define which categories to include
+      def included_category_types
+        raise NotImplementedError, "Subclasses must define included_category_types"
+      end
+      
+      # Get categories that should be in this report
+      def relevant_categories
+        @model.categories.select do |cat|
+          included_category_types.include?(cat.type) &&
+          matches_filters?(cat) &&
+          category_has_relevant_variables?(cat)
+        end
+      end
+      
+      # Check if category has variables that match project filter
+      def category_has_relevant_variables?(category)
+        return true unless @filters[:project]
+        
+        # Check if any variable in this category or its descendants matches the project
+        all_vars = category.variables + category.descendants.flat_map(&:variables)
+        return false if all_vars.empty?
+        
+        all_vars.any? { |var| variable_matches_project?(var, @filters[:project]) }
+      end
+      
+      # Check if a variable matches the project filter
+      def variable_matches_project?(variable, project_filter)
+        return true unless project_filter
+        
+        variable_project = get_variable_project(variable[:name])
+        variable_project == project_filter
+      end
+      
+      # Get project tag for a variable
+      def get_variable_project(variable_name)
+        # Check in temporal values metadata
+        temporal_value = @model.calculator.instance_variable_get(:@temporal_values)[variable_name]
+        if temporal_value
+          # Get project from most recent period metadata
+          periods = temporal_value.instance_variable_get(:@periods)
+          if periods && periods.any?
+            latest_period = periods.last
+            return latest_period[:metadata][:project] if latest_period[:metadata]
+          end
+        end
+        
+        # Check in calculated variables metadata
+        var_def = @model.calculator.variables[variable_name]
+        if var_def.is_a?(Hash) && var_def[:type] == :calculated
+          return var_def[:project]
+        end
+        
+        # Check in category variables
+        @model.categories.each do |cat|
+          var = (cat.variables + cat.descendants.flat_map(&:variables)).find { |v| v[:name] == variable_name }
+          return var[:project] if var && var[:project]
+        end
+        
+        nil
+      end
+      
+      # Generate report data structure
+      def generate
+        {
+          metadata: build_metadata,
+          sections: build_sections,
+          totals: calculate_totals,
+          period: { start: @start_date, end: @end_date },
+          currency: @output_currency
+        }
+      end
+      
+      # Output to a specific format
+      def output(format_class, options = {})
+        output_handler = format_class.new(self, options)
+        output_handler.generate
+      end
+      
+      protected
+      
+      def build_metadata
+        {
+          report_type: self.class.name.split('::').last,
+          generated_at: Time.now,
+          currency: @output_currency,
+          filters: @filters
+        }
+      end
+      
+      def build_sections
+        raise NotImplementedError, "Subclasses must implement build_sections"
+      end
+      
+      def calculate_totals
+        raise NotImplementedError, "Subclasses must implement calculate_totals"
+      end
+      
+      def calculate_value(variable_name, date = @end_date, period_type: :annual)
+        @model.variable_value(variable_name,
+          date: date,
+          period_type: period_type
+        )
+      end
+      
+      # Get period type for this report
+      def period_type
+        @model.determine_period_type(@start_date, @end_date)
+      end
+      
+      def format_money(value)
+        return 0 unless value
+        
+        if value.is_a?(Money)
+          value
+        else
+          Money.new((value * 100).to_i, @output_currency)
+        end
+      end
+      
+      def humanize_name(name)
+        name.to_s.split('_').map(&:capitalize).join(' ')
+      end
+      
+      # Generate dates for a period range
+      def generate_period_dates(start_date, end_date, frequency)
+        dates = []
+        current = parse_date(start_date)
+        end_dt = parse_date(end_date)
+        
+        while current <= end_dt
+          dates << current
+          current = case frequency
+          when :daily
+            current + 1
+          when :weekly
+            current + 7
+          when :monthly
+            current >> 1
+          when :quarterly
+            current >> 3
+          when :annual
+            current >> 12
+          else
+            current >> 1 # Default monthly
+          end
+        end
+        
+        dates
+      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}-\d{2}$/ # YYYY-MM format
+            Date.parse("#{date}-01")
+          else
+            Date.parse(date)
+          end
+        when Time
+          date.to_date
+        when Integer
+          # Assume year
+          Date.new(date, 1, 1)
+        else
+          date
+        end
+      end
+      
+      # Get section value from report data
+      def extract_section_value(report_data, section_name)
+        sections = report_data[:sections] || {}
+        section = sections[section_name.to_sym] || sections[section_name.to_s]
+        section ? (section[:total] || section[:value] || 0) : nil
+      end
+      
+      # Count items in a section
+      def count_section_items(report_data, section_name)
+        sections = report_data[:sections] || {}
+        section = sections[section_name.to_sym] || sections[section_name.to_s]
+        return 0 unless section
+        
+        items = section[:items] || []
+        count = items.length
+        
+        # Count subcategories recursively
+        items.each do |item|
+          if item[:subcategories]
+            count += item[:subcategories].length
+          end
+        end
+        
+        count
+      end
+      
+      private
+      
+      def matches_filters?(category)
+        return true if @filters.empty?
+        
+        # Support filtering by name pattern, parent, project, etc.
+        @filters.all? do |key, value|
+          case key
+          when :name_includes
+            category.name.to_s.include?(value.to_s)
+          when :parent
+            category.parent&.name == value
+          when :exclude
+            !Array(value).include?(category.name)
+          when :only
+            Array(value).include?(category.name)
+          when :project
+            # Project filtering is handled by category_has_relevant_variables?
+            true
+          else
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fin_it/reports/cash_flow_statement.rb

@@ -0,0 +1,480 @@
+# frozen_string_literal: true
+
+module FinIt
+  module Reports
+    class CashFlowStatement < BaseReport
+      attr_accessor :method, :display_mode
+
+      # Include categories that affect cash flow
+      def included_category_types
+        [:cash_inflow, :cash_outflow, :income, :expense, :asset, :liability]
+      end
+
+      def initialize(model, start_date:, end_date:, output_currency: 'USD', filters: {}, method: :indirect, display_mode: :standard)
+        super(model, start_date: start_date, end_date: end_date, output_currency: output_currency, filters: filters)
+        @method = method # :direct or :indirect
+        @display_mode = display_mode # :standard (3 sections) or :simple (cash in/out)
+        @period_type = model.determine_period_type(start_date, end_date)
+      end
+
+      def generate
+        data = super
+        data[:method] = @method
+        data[:display_mode] = @display_mode
+        data
+      end
+
+      def build_sections
+        sections = {}
+
+        case @display_mode
+        when :simple
+          sections.merge!(build_simple_sections)
+        else # :standard
+          sections.merge!(build_standard_sections)
+        end
+
+        sections
+      end
+
+      def calculate_totals
+        sections = build_sections
+
+        if @display_mode == :simple
+          {
+            cash_in: sections[:cash_in][:total] || 0,
+            cash_out: sections[:cash_out][:total] || 0,
+            operating: 0,
+            investing: 0,
+            financing: 0,
+            net_change_in_cash: sections[:net_change_in_cash][:total] || 0,
+            beginning_cash: sections[:beginning_cash][:total] || 0,
+            ending_cash: sections[:ending_cash][:total] || 0
+          }
+        else
+          {
+            operating: sections[:operating][:total] || 0,
+            investing: sections[:investing][:total] || 0,
+            financing: sections[:financing][:total] || 0,
+            net_change_in_cash: sections[:net_change_in_cash][:total] || 0,
+            beginning_cash: sections[:beginning_cash][:total] || 0,
+            ending_cash: sections[:ending_cash][:total] || 0
+          }
+        end
+      end
+
+      # Generate monthly reports 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,
+            method: @method,
+            display_mode: @display_mode
+          )
+          {
+            period: { start: month_start, end: month_end },
+            report: report.generate
+          }
+        end
+      end
+
+      # Get summary statistics for periods
+      def period_summary(period_type: :monthly)
+        periods = get_periods(frequency: period_type)
+        summaries = periods.map do |date|
+          period_start = case period_type
+          when :monthly
+            Date.new(date.year, date.month, 1)
+          when :quarterly
+            quarter_month = ((date.month - 1) / 3) * 3 + 1
+            Date.new(date.year, quarter_month, 1)
+          when :annual
+            Date.new(date.year, 1, 1)
+          else
+            date
+          end
+
+          period_end = case period_type
+          when :monthly
+            Date.new(date.year, date.month, -1)
+          when :quarterly
+            quarter_month = ((date.month - 1) / 3) * 3 + 3
+            Date.new(date.year, quarter_month, -1)
+          when :annual
+            Date.new(date.year, 12, 31)
+          else
+            date
+          end
+
+          report = self.class.new(
+            @model,
+            start_date: period_start,
+            end_date: period_end,
+            output_currency: @output_currency,
+            filters: @filters,
+            method: @method,
+            display_mode: @display_mode
+          )
+
+          report_data = report.generate
+          totals = report_data[:totals] || {}
+
+          {
+            period: { start: period_start, end: period_end },
+            report: report_data,
+            operating: totals[:operating] || 0,
+            investing: totals[:investing] || 0,
+            financing: totals[:financing] || 0,
+            net_change_in_cash: totals[:net_change_in_cash] || 0
+          }
+        end
+
+        {
+          frequency: period_type,
+          periods: summaries,
+          summary: {
+            total_operating: summaries.sum { |s| s[:operating] || 0 },
+            total_investing: summaries.sum { |s| s[:investing] || 0 },
+            total_financing: summaries.sum { |s| s[:financing] || 0 },
+            total_net_change: summaries.sum { |s| s[:net_change_in_cash] || 0 },
+            period_count: summaries.length
+          }
+        }
+      end
+
+      def get_periods(frequency: :monthly)
+        generate_period_dates(@start_date, @end_date, frequency)
+      end
+
+      private
+
+      def build_standard_sections
+        sections = {}
+
+        # OPERATING ACTIVITIES
+        sections[:operating] = build_operating_section
+
+        # INVESTING ACTIVITIES
+        sections[:investing] = build_investing_section
+
+        # FINANCING ACTIVITIES
+        sections[:financing] = build_financing_section
+
+        # Calculate totals
+        operating_total = sections[:operating][:total] || 0
+        investing_total = sections[:investing][:total] || 0
+        financing_total = sections[:financing][:total] || 0
+
+        net_change = operating_total + investing_total + financing_total
+
+        # NET CHANGE IN CASH
+        sections[:net_change_in_cash] = {
+          label: "Net Change in Cash",
+          formula: "operating + investing + financing",
+          value: net_change,
+          total: net_change
+        }
+
+        # BEGINNING CASH BALANCE
+        beginning_cash = calculate_beginning_cash
+        sections[:beginning_cash] = {
+          label: "Beginning Cash Balance",
+          value: beginning_cash,
+          total: beginning_cash
+        }
+
+        # ENDING CASH BALANCE
+        ending_cash = beginning_cash + net_change
+        sections[:ending_cash] = {
+          label: "Ending Cash Balance",
+          formula: "beginning_cash + net_change_in_cash",
+          value: ending_cash,
+          total: ending_cash
+        }
+
+        sections
+      end
+
+      def build_simple_sections
+        sections = {}
+
+        # Simple mode: just cash in and cash out
+        cash_in = calculate_total_cash_in
+        cash_out = calculate_total_cash_out
+
+        sections[:cash_in] = {
+          name: "Cash Inflows",
+          items: build_cash_in_items,
+          total: cash_in,
+          formula: "total of all cash inflows"
+        }
+
+        sections[:cash_out] = {
+          name: "Cash Outflows",
+          items: build_cash_out_items,
+          total: cash_out,
+          formula: "total of all cash outflows"
+        }
+
+        net_change = cash_in - cash_out
+
+        sections[:net_change_in_cash] = {
+          label: "Net Change in Cash",
+          formula: "cash_in - cash_out",
+          value: net_change,
+          total: net_change
+        }
+
+        beginning_cash = calculate_beginning_cash
+        sections[:beginning_cash] = {
+          label: "Beginning Cash Balance",
+          value: beginning_cash,
+          total: beginning_cash
+        }
+
+        ending_cash = beginning_cash + net_change
+        sections[:ending_cash] = {
+          label: "Ending Cash Balance",
+          formula: "beginning_cash + net_change_in_cash",
+          value: ending_cash,
+          total: ending_cash
+        }
+
+        sections
+      end
+
+      def build_operating_section
+        items = []
+        total = 0
+
+        case @method
+        when :indirect
+          # Start with net income
+          net_income = @model.period_net_income(@start_date, @end_date,
+            output_currency: @output_currency, filters: @filters)
+
+          items << {
+            name: :net_income,
+            display_name: "Net Income",
+            value: net_income,
+            indent: 0
+          }
+          total += net_income
+
+          # Add back non-cash expenses (depreciation, amortization)
+          # For now, we assume all income/expenses are cash-based
+          # Future: detect and add back depreciation accounts
+
+          # Working capital changes would go here
+          # For the concert model, all transactions flow through checking
+          # so net income = operating cash flow
+
+        when :direct
+          # Direct method: list actual cash receipts and payments
+          # Use cash_inflow and cash_outflow categories
+          cash_inflow_categories = @model.categories.select { |c| c.type == :cash_inflow }
+          cash_outflow_categories = @model.categories.select { |c| c.type == :cash_outflow }
+
+          # Add cash inflows
+          cash_inflow_categories.each do |category|
+            item = build_category_item(category)
+            next unless item
+            items << item
+            total += item[:value] || 0
+          end
+
+          # Add cash outflows (as negative)
+          cash_outflow_categories.each do |category|
+            item = build_category_item(category)
+            next unless item
+            item[:value] = -(item[:value] || 0).abs
+            items << item
+            total += item[:value]
+          end
+        end
+
+        {
+          name: "Operating Activities",
+          items: items,
+          total: total,
+          formula: @method == :indirect ? "net_income + adjustments" : "cash_receipts - cash_payments"
+        }
+      end
+
+      def build_investing_section
+        items = []
+        total = 0
+
+        # Look for fixed asset accounts and calculate changes
+        # For the concert model, there are no investing activities
+        # Future: detect asset purchases/sales
+
+        {
+          name: "Investing Activities",
+          items: items,
+          total: total,
+          formula: "asset_sales - asset_purchases"
+        }
+      end
+
+      def build_financing_section
+        items = []
+        total = 0
+
+        # Look for liability/equity changes
+        # For the concert model, there are no financing activities
+        # Future: detect debt/equity transactions
+
+        {
+          name: "Financing Activities",
+          items: items,
+          total: total,
+          formula: "debt_proceeds + equity_contributions - debt_payments - dividends"
+        }
+      end
+
+      def calculate_beginning_cash
+        # Get cash balance at start of period
+        cash_accounts = @model.accounts.values.select { |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        }
+
+        # Calculate balance at start_date - 1 day (end of previous period)
+        previous_date = @start_date - 1
+
+        # If previous date is before model start, use opening balance
+        if previous_date < @model.start_date
+          cash_accounts.sum { |account| account.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_total_cash_in
+        # Sum all positive flows to cash accounts
+        cash_accounts = @model.accounts.values.select { |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        }
+
+        total = 0
+        cash_accounts.each do |account|
+          flow = @model.account_period_flow(account.name, @start_date, @end_date)
+          total += flow if flow > 0
+        end
+        total
+      end
+
+      def calculate_total_cash_out
+        # Sum all negative flows from cash accounts (as positive number)
+        cash_accounts = @model.accounts.values.select { |acc|
+          acc.type == :asset && is_cash_account?(acc)
+        }
+
+        total = 0
+        cash_accounts.each do |account|
+          flow = @model.account_period_flow(account.name, @start_date, @end_date)
+          total += flow.abs if flow < 0
+        end
+        total
+      end
+
+      def build_cash_in_items
+        items = []
+
+        # Group cash inflows by source (income categories)
+        income_categories = @model.categories.select { |c| c.type == :income }
+
+        income_categories.each do |category|
+          value = @model.category_total_for_period(
+            category,
+            @start_date,
+            @end_date,
+            period_type: @period_type,
+            output_currency: @output_currency,
+            filters: @filters
+          )
+
+          next if value == 0
+
+          items << {
+            name: category.name,
+            display_name: category.description || humanize_name(category.name),
+            value: value,
+            indent: 0
+          }
+        end
+
+        items
+      end
+
+      def build_cash_out_items
+        items = []
+
+        # Group cash outflows by category (expense categories)
+        expense_categories = @model.categories.select { |c| c.type == :expense }
+
+        expense_categories.each do |category|
+          value = @model.category_total_for_period(
+            category,
+            @start_date,
+            @end_date,
+            period_type: @period_type,
+            output_currency: @output_currency,
+            filters: @filters
+          )
+
+          # Expense values are typically negative in account flows
+          value = value.abs if value.is_a?(Numeric)
+
+          next if value == 0
+
+          items << {
+            name: category.name,
+            display_name: category.description || humanize_name(category.name),
+            value: value,
+            indent: 0
+          }
+        end
+
+        items
+      end
+
+      def build_category_item(category)
+        value = @model.category_total_for_period(
+          category,
+          @start_date,
+          @end_date,
+          period_type: @period_type,
+          output_currency: @output_currency,
+          filters: @filters
+        )
+
+        return nil if value == 0
+
+        {
+          name: category.name,
+          display_name: category.description || humanize_name(category.name),
+          value: value,
+          indent: 0
+        }
+      end
+
+      def is_cash_account?(account)
+        # Determine if account is a cash account
+        # Check by name patterns
+        name = account.name.to_s.downcase
+        cash_patterns = ['cash', 'checking', 'savings', 'bank', 'money_market']
+        cash_patterns.any? { |pattern| name.include?(pattern) }
+      end
+    end
+  end
+end