refactor(income-statement): share scoping SQL across all four query classes (#3408)

#3404 added DailyExpenseTotals with scoping SQL that mirrored Totals, and
the same fragments (classification CASE, currency-converted amount,
entries/accounts/exchange-rates joins, budget-excluded kinds, tax-advantaged
and finance-account scoping) were already duplicated in FamilyStats and
CategoryStats. This extracts them into
IncomeStatement::ScopedTransactionsQuery so every income statement number is
computed from one definition of what counts as a reportable transaction.

No behavior change: only whitespace in the generated SQL differs. A new
equivalence test runs each refactored class against a verbatim legacy copy
(test/support/legacy_income_statement_*.rb) over the class's full option
matrix (trade inclusion, account scoping, stats interval) on a dataset that
exercises every scoping rule, and asserts identical rows.

test/support/legacy_income_statement_category_stats.rb

@@ -0,0 +1,104 @@
+# Verbatim copy of IncomeStatement::CategoryStats as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+class LegacyIncomeStatementCategoryStats
+  def initialize(family, interval: "month", account_ids: nil)
+    @family = family
+    @interval = interval
+    @account_ids = account_ids
+  end
+
+  def call
+    return [] if @account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(sanitized_query_sql).map do |row|
+      StatRow.new(
+        category_id: row["category_id"],
+        classification: row["classification"],
+        median: row["median"],
+        avg: row["avg"]
+      )
+    end
+  end
+
+  private
+    StatRow = Data.define(:category_id, :classification, :median, :avg)
+
+    def sanitized_query_sql
+      ActiveRecord::Base.sanitize_sql_array([
+        query_sql,
+        sql_params
+      ])
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        interval: @interval,
+        family_id: @family.id
+      }
+
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      params
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def pending_providers_sql
+      Transaction.pending_providers_sql("t")
+    end
+
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    def scope_to_account_ids_sql
+      return "" if @account_ids.nil?
+      ActiveRecord::Base.sanitize_sql([ "AND a.id IN (?)", @account_ids ])
+    end
+
+    def query_sql
+      <<~SQL
+        WITH period_totals AS (
+          SELECT
+            c.id as category_id,
+            date_trunc(:interval, ae.date) as period,
+            CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+            SUM(CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END) as total
+          FROM transactions t
+          JOIN entries ae ON ae.entryable_id = t.id AND ae.entryable_type = 'Transaction'
+          JOIN accounts a ON a.id = ae.account_id
+          LEFT JOIN categories c ON c.id = t.category_id
+          LEFT JOIN exchange_rates er ON (
+            er.date = ae.date AND
+            er.from_currency = ae.currency AND
+            er.to_currency = :target_currency
+          )
+          WHERE a.family_id = :family_id
+            AND t.kind NOT IN (#{budget_excluded_kinds_sql})
+            AND ae.excluded = false
+            AND a.exclude_from_reports = false
+            #{pending_providers_sql}
+            #{exclude_tax_advantaged_sql}
+            #{scope_to_account_ids_sql}
+          GROUP BY c.id, period, CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+        )
+        SELECT
+          category_id,
+          classification,
+          ABS(PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY total)) as median,
+          ABS(AVG(total)) as avg
+        FROM period_totals
+        GROUP BY category_id, classification;
+      SQL
+    end
+end

test/support/legacy_income_statement_daily_expense_totals.rb

@@ -0,0 +1,115 @@
+# Verbatim copy of IncomeStatement::DailyExpenseTotals as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+# Per-day expense totals (in the family's currency) for a period, used by the
+# dashboard's cumulative spending chart. Follows the same scoping rules as
+# IncomeStatement::Totals (visible, posted, budget-included transactions in
+# report-included accounts, converted at the day's exchange rate) so the
+# series always agrees with the totals shown elsewhere on the dashboard.
+class LegacyIncomeStatementDailyExpenseTotals
+  def initialize(family, transactions_scope:, date_range:, included_account_ids: nil)
+    @family = family
+    @transactions_scope = transactions_scope
+    @date_range = date_range
+    @included_account_ids = included_account_ids
+
+    validate_date_range!
+  end
+
+  def call
+    # No finance accounts means no transactions to report
+    return [] if @included_account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(query_sql).map do |row|
+      DailyTotal.new(date: row["day"].to_date, total: row["total"])
+    end
+  end
+
+  private
+    DailyTotal = Data.define(:date, :total)
+
+    def query_sql
+      ActiveRecord::Base.sanitize_sql_array([ query_sql_body, sql_params ])
+    end
+
+    # Mirrors IncomeStatement::Totals' transactions subquery, but groups by
+    # entry date instead of category and keeps only the expense rows. The
+    # classification CASE is repeated in the GROUP BY (rather than referenced
+    # by alias) because only some databases accept aliases there.
+    def query_sql_body
+      <<~SQL
+        SELECT day, total FROM (
+          SELECT
+            ae.date as day,
+            CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+            ABS(SUM(CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END)) as total
+          FROM (#{@transactions_scope.to_sql}) at
+          JOIN entries ae ON ae.entryable_id = at.id AND ae.entryable_type = 'Transaction'
+          JOIN accounts a ON a.id = ae.account_id
+          LEFT JOIN exchange_rates er ON (
+            er.date = ae.date AND
+            er.from_currency = ae.currency AND
+            er.to_currency = :target_currency
+          )
+          WHERE at.kind NOT IN (#{budget_excluded_kinds_sql})
+            AND (
+              at.investment_activity_label IS NULL
+              OR at.investment_activity_label NOT IN ('Transfer', 'Sweep In', 'Sweep Out', 'Exchange')
+            )
+            AND ae.excluded = false
+            AND a.family_id = :family_id
+            AND a.status IN ('draft', 'active')
+            AND a.exclude_from_reports = false
+            #{exclude_tax_advantaged_sql}
+            #{include_finance_accounts_sql}
+          GROUP BY ae.date, CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+        ) daily
+        WHERE classification = 'expense'
+        ORDER BY day
+      SQL
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        family_id: @family.id,
+        start_date: @date_range.begin,
+        end_date: @date_range.end
+      }
+
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      params[:included_account_ids] = @included_account_ids if @included_account_ids
+
+      params
+    end
+
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    def include_finance_accounts_sql
+      return "" if @included_account_ids.nil?
+      "AND a.id IN (:included_account_ids)"
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def validate_date_range!
+      unless @date_range.is_a?(Range)
+        raise ArgumentError, "date_range must be a Range, got #{@date_range.class}"
+      end
+
+      unless @date_range.begin.respond_to?(:to_date) && @date_range.end.respond_to?(:to_date)
+        raise ArgumentError, "date_range must contain date-like objects"
+      end
+    end
+end

test/support/legacy_income_statement_family_stats.rb

@@ -0,0 +1,100 @@
+# Verbatim copy of IncomeStatement::FamilyStats as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+class LegacyIncomeStatementFamilyStats
+  def initialize(family, interval: "month", account_ids: nil)
+    @family = family
+    @interval = interval
+    @account_ids = account_ids
+  end
+
+  def call
+    return [] if @account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(sanitized_query_sql).map do |row|
+      StatRow.new(
+        classification: row["classification"],
+        median: row["median"],
+        avg: row["avg"]
+      )
+    end
+  end
+
+  private
+    StatRow = Data.define(:classification, :median, :avg)
+
+    def sanitized_query_sql
+      ActiveRecord::Base.sanitize_sql_array([
+        query_sql,
+        sql_params
+      ])
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        interval: @interval,
+        family_id: @family.id
+      }
+
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      params
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def pending_providers_sql
+      Transaction.pending_providers_sql("t")
+    end
+
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    def scope_to_account_ids_sql
+      return "" if @account_ids.nil?
+      ActiveRecord::Base.sanitize_sql([ "AND a.id IN (?)", @account_ids ])
+    end
+
+    def query_sql
+      <<~SQL
+        WITH period_totals AS (
+          SELECT
+            date_trunc(:interval, ae.date) as period,
+            CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+            SUM(CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END) as total
+          FROM transactions t
+          JOIN entries ae ON ae.entryable_id = t.id AND ae.entryable_type = 'Transaction'
+          JOIN accounts a ON a.id = ae.account_id
+          LEFT JOIN exchange_rates er ON (
+            er.date = ae.date AND
+            er.from_currency = ae.currency AND
+            er.to_currency = :target_currency
+          )
+          WHERE a.family_id = :family_id
+            AND t.kind NOT IN (#{budget_excluded_kinds_sql})
+            AND ae.excluded = false
+            AND a.exclude_from_reports = false
+            #{pending_providers_sql}
+            #{exclude_tax_advantaged_sql}
+            #{scope_to_account_ids_sql}
+          GROUP BY period, CASE WHEN t.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+        )
+        SELECT
+          classification,
+          ABS(PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY total)) as median,
+          ABS(AVG(total)) as avg
+        FROM period_totals
+        GROUP BY classification;
+      SQL
+    end
+end

test/support/legacy_income_statement_totals.rb

@@ -0,0 +1,183 @@
+# Verbatim copy of IncomeStatement::Totals as it existed on main before the
+# IncomeStatement::ScopedTransactionsQuery refactor (base commit 947fe832),
+# renamed so both implementations can run side by side.
+# ScopedTransactionsQueryEquivalenceTest runs each refactored class and its
+# legacy counterpart over the same data and option matrix and asserts
+# identical results. Delete once the refactor is merged and trusted.
+class LegacyIncomeStatementTotals
+  def initialize(family, transactions_scope:, date_range:, include_trades: true, included_account_ids: nil)
+    @family = family
+    @transactions_scope = transactions_scope
+    @date_range = date_range
+    @include_trades = include_trades
+    @included_account_ids = included_account_ids
+
+    validate_date_range!
+  end
+
+  def call
+    # No finance accounts means no transactions to report
+    return [] if @included_account_ids&.empty?
+
+    ActiveRecord::Base.connection.select_all(query_sql).map do |row|
+      TotalsRow.new(
+        parent_category_id: row["parent_category_id"],
+        category_id: row["category_id"],
+        classification: row["classification"],
+        total: row["total"],
+        transactions_count: row["transactions_count"],
+        is_uncategorized_investment: row["is_uncategorized_investment"]
+      )
+    end
+  end
+
+  private
+    TotalsRow = Data.define(:parent_category_id, :category_id, :classification, :total, :transactions_count, :is_uncategorized_investment)
+
+    def query_sql
+      ActiveRecord::Base.sanitize_sql_array([
+        @include_trades ? combined_query_sql : transactions_only_query_sql,
+        sql_params
+      ])
+    end
+
+    # Combined query that includes both transactions and trades
+    def combined_query_sql
+      <<~SQL
+        SELECT
+          category_id,
+          parent_category_id,
+          classification,
+          is_uncategorized_investment,
+          SUM(total) as total,
+          SUM(entry_count) as transactions_count
+        FROM (
+          #{transactions_subquery_sql}
+          UNION ALL
+          #{trades_subquery_sql}
+        ) combined
+        GROUP BY category_id, parent_category_id, classification, is_uncategorized_investment;
+      SQL
+    end
+
+    # Original transactions-only query (for backwards compatibility)
+    def transactions_only_query_sql
+      <<~SQL
+        SELECT
+          c.id as category_id,
+          c.parent_id as parent_category_id,
+          CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+          ABS(SUM(CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END)) as total,
+          COUNT(ae.id) as transactions_count,
+          false as is_uncategorized_investment
+        FROM (#{@transactions_scope.to_sql}) at
+        JOIN entries ae ON ae.entryable_id = at.id AND ae.entryable_type = 'Transaction'
+        JOIN accounts a ON a.id = ae.account_id
+        LEFT JOIN categories c ON c.id = at.category_id
+        LEFT JOIN exchange_rates er ON (
+          er.date = ae.date AND
+          er.from_currency = ae.currency AND
+          er.to_currency = :target_currency
+        )
+        WHERE at.kind NOT IN (#{budget_excluded_kinds_sql})
+          AND ae.excluded = false
+          AND a.family_id = :family_id
+          AND a.status IN ('draft', 'active')
+          AND a.exclude_from_reports = false
+          #{exclude_tax_advantaged_sql}
+          #{include_finance_accounts_sql}
+        GROUP BY c.id, c.parent_id, CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END;
+      SQL
+    end
+
+    def transactions_subquery_sql
+      <<~SQL
+        SELECT
+          c.id as category_id,
+          c.parent_id as parent_category_id,
+          CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END as classification,
+          ABS(SUM(CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN ABS(ae.amount * COALESCE(er.rate, 1)) ELSE ae.amount * COALESCE(er.rate, 1) END)) as total,
+          COUNT(ae.id) as entry_count,
+          false as is_uncategorized_investment
+        FROM (#{@transactions_scope.to_sql}) at
+        JOIN entries ae ON ae.entryable_id = at.id AND ae.entryable_type = 'Transaction'
+        JOIN accounts a ON a.id = ae.account_id
+        LEFT JOIN categories c ON c.id = at.category_id
+        LEFT JOIN exchange_rates er ON (
+          er.date = ae.date AND
+          er.from_currency = ae.currency AND
+          er.to_currency = :target_currency
+        )
+        WHERE at.kind NOT IN (#{budget_excluded_kinds_sql})
+          AND (
+            at.investment_activity_label IS NULL
+            OR at.investment_activity_label NOT IN ('Transfer', 'Sweep In', 'Sweep Out', 'Exchange')
+          )
+          AND ae.excluded = false
+          AND a.family_id = :family_id
+          AND a.status IN ('draft', 'active')
+          AND a.exclude_from_reports = false
+          #{exclude_tax_advantaged_sql}
+          #{include_finance_accounts_sql}
+        GROUP BY c.id, c.parent_id, CASE WHEN at.kind IN ('investment_contribution', 'loan_payment') THEN 'expense' WHEN ae.amount < 0 THEN 'income' ELSE 'expense' END
+      SQL
+    end
+
+    def trades_subquery_sql
+      # Trades are completely excluded from income/expense budgets
+      # Rationale: Trades represent portfolio rebalancing, not cash flow
+      # Example: Selling $10k AAPL to buy MSFT = no net worth change, not an expense
+      # Contributions/withdrawals are tracked separately as Transactions with activity labels
+      <<~SQL
+        SELECT NULL as category_id, NULL as parent_category_id, NULL as classification,
+               NULL as total, NULL as entry_count, NULL as is_uncategorized_investment
+        WHERE false
+      SQL
+    end
+
+    def sql_params
+      params = {
+        target_currency: @family.currency,
+        family_id: @family.id,
+        start_date: @date_range.begin,
+        end_date: @date_range.end
+      }
+
+      # Add tax-advantaged account IDs if any exist
+      ids = @family.tax_advantaged_account_ids
+      params[:tax_advantaged_account_ids] = ids if ids.present?
+
+      # Add included account IDs for per-user finance scoping
+      params[:included_account_ids] = @included_account_ids if @included_account_ids
+
+      params
+    end
+
+    # Returns SQL clause to exclude tax-advantaged accounts from budget calculations.
+    # Tax-advantaged accounts (401k, IRA, HSA, etc.) are retirement savings, not daily expenses.
+    def exclude_tax_advantaged_sql
+      ids = @family.tax_advantaged_account_ids
+      return "" if ids.empty?
+      "AND a.id NOT IN (:tax_advantaged_account_ids)"
+    end
+
+    # Returns SQL clause to filter to only accounts included in the user's finances.
+    def include_finance_accounts_sql
+      return "" if @included_account_ids.nil?
+      "AND a.id IN (:included_account_ids)"
+    end
+
+    def budget_excluded_kinds_sql
+      @budget_excluded_kinds_sql ||= Transaction::BUDGET_EXCLUDED_KINDS.map { |k| "'#{k}'" }.join(", ")
+    end
+
+    def validate_date_range!
+      unless @date_range.is_a?(Range)
+        raise ArgumentError, "date_range must be a Range, got #{@date_range.class}"
+      end
+
+      unless @date_range.begin.respond_to?(:to_date) && @date_range.end.respond_to?(:to_date)
+        raise ArgumentError, "date_range must contain date-like objects"
+      end
+    end
+end