fin_it 0.1.0

data/test/fin_it/reports/scenario_comparison_test.rb

@@ -0,0 +1,414 @@
+# frozen_string_literal: true
+
+require_relative "../../test_helper"
+
+class ScenarioComparisonTest < Minitest::Test
+  def setup
+    @model = FinIt.define(default_currency: 'USD') do
+      config do
+        start_date 2024
+      end
+
+      account :checking do
+        type :asset
+        currency 'USD'
+        opening_balance 10_000
+      end
+
+      # Driver variables
+      category :drivers, type: :driver do
+        variable :units_sold do
+          value 100
+        end
+
+        variable :price_per_unit do
+          value 50
+        end
+      end
+
+      # Income categories
+      category :income, type: :income,
+               default_account: :checking,
+               defaults: { frequency: :monthly, start_date: "2024-01-01", end_date: "2024-12-31" } do
+
+        calculated :product_sales,
+          formula: "units_sold * price_per_unit"
+
+        variable :service_revenue, currency: 'USD' do
+          value 2_000, start_date: "2024-01-01", end_date: "2024-12-31"
+        end
+      end
+
+      # Expense categories
+      category :expenses, type: :expense,
+               default_account: :checking,
+               defaults: { frequency: :monthly, start_date: "2024-01-01", end_date: "2024-12-31" } do
+
+        variable :operating_expenses, currency: 'USD' do
+          value 1_500, start_date: "2024-01-01", end_date: "2024-12-31"
+        end
+      end
+
+      # Define plans
+      plan :growth_scenario, description: "10% revenue growth" do
+        scale :service_revenue, 1.10
+      end
+
+      plan :cost_reduction, description: "Reduce costs by 20%" do
+        scale :operating_expenses, 0.80
+      end
+    end
+
+    @start_date = Date.new(2024, 1, 1)
+    @end_date = Date.new(2024, 12, 31)
+  end
+
+  def test_scenario_comparison_basic
+    # Generate transactions for base model
+    @model.generate_transactions(@end_date)
+
+    # Create scenarios
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    cost_model = @model.with_plan(:cost_reduction)
+    cost_model.generate_transactions(@end_date)
+
+    # Create comparison report
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model, cost_reduction: cost_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      output_currency: 'USD'
+    )
+
+    data = comparison.generate
+
+    # Verify structure
+    assert_equal "ScenarioComparison", data[:report_type]
+    assert data[:metadata]
+    assert data[:base]
+    assert data[:scenarios]
+    assert data[:variances]
+
+    # Verify metadata
+    assert_equal @start_date, data[:metadata][:start_date]
+    assert_equal @end_date, data[:metadata][:end_date]
+    assert_equal 'USD', data[:metadata][:currency]
+    assert_includes data[:metadata][:scenario_names], :growth
+    assert_includes data[:metadata][:scenario_names], :cost_reduction
+  end
+
+  def test_scenario_comparison_metrics
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [:net_income, :total_revenue, :total_expenses]
+    )
+
+    data = comparison.generate
+
+    # Verify metrics are calculated
+    assert data[:base][:net_income]
+    assert data[:base][:total_revenue]
+    assert data[:base][:total_expenses]
+
+    # Verify scenario metrics
+    assert data[:scenarios][:growth][:net_income]
+    assert data[:scenarios][:growth][:total_revenue]
+    assert data[:scenarios][:growth][:total_expenses]
+  end
+
+  def test_scenario_comparison_variances
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [:net_income]
+    )
+
+    data = comparison.generate
+
+    # Verify variance is calculated
+    assert data[:variances][:growth]
+    assert data[:variances][:growth][:net_income]
+    assert data[:variances][:growth][:net_income][:absolute]
+    assert data[:variances][:growth][:net_income][:percentage]
+
+    # Growth scenario should have higher net income (positive variance)
+    variance = data[:variances][:growth][:net_income]
+    assert variance[:absolute] > 0, "Growth scenario should have higher net income"
+    assert variance[:percentage] > 0, "Growth percentage should be positive"
+  end
+
+  def test_scenario_comparison_console_output
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date
+    )
+
+    # Capture stdout
+    output = capture_io do
+      comparison.output(FinIt::Outputs::ConsoleOutput)
+    end.first
+
+    # Verify output contains expected elements
+    assert_match(/SCENARIO COMPARISON/, output)
+    assert_match(/Net Income/, output)
+    assert_match(/Base/, output)
+    assert_match(/Growth/, output)
+  end
+
+  def test_scenario_comparison_custom_metrics
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    # Test with custom metrics including ending_cash
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [:net_income, :ending_cash]
+    )
+
+    data = comparison.generate
+
+    # Verify all requested metrics are present
+    assert data[:base][:net_income]
+    assert data[:base][:ending_cash]
+    assert data[:scenarios][:growth][:net_income]
+    assert data[:scenarios][:growth][:ending_cash]
+  end
+
+  def test_scenario_comparison_multiple_scenarios
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    cost_model = @model.with_plan(:cost_reduction)
+    cost_model.generate_transactions(@end_date)
+
+    combined_model = @model.with_plans(:growth_scenario, :cost_reduction)
+    combined_model.generate_transactions(@end_date)
+
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: {
+        growth: growth_model,
+        cost_cut: cost_model,
+        combined: combined_model
+      },
+      start_date: @start_date,
+      end_date: @end_date
+    )
+
+    data = comparison.generate
+
+    # Verify all scenarios are present
+    assert_equal 3, data[:scenarios].keys.length
+    assert data[:scenarios][:growth]
+    assert data[:scenarios][:cost_cut]
+    assert data[:scenarios][:combined]
+
+    # Verify variances for all scenarios
+    assert_equal 3, data[:variances].keys.length
+  end
+
+  def test_scenario_comparison_hash_metrics
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    # Test hash format metrics
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [
+        :net_income,  # Symbol format
+        { variable: :total_revenue, label: "Annual Revenue" },  # Hash format
+        { variable: :total_expenses, period_type: :monthly, label: "Monthly Expenses" }
+      ]
+    )
+
+    data = comparison.generate
+
+    # Verify normalized metrics have correct labels
+    normalized = data[:metadata][:normalized_metrics]
+    assert_equal 3, normalized.length
+    assert_equal "Net Income", normalized[0][:label]
+    assert_equal "Annual Revenue", normalized[1][:label]
+    assert_equal "Monthly Expenses", normalized[2][:label]
+
+    # Verify data is present
+    assert data[:base][:net_income]
+    assert data[:base][:total_revenue]
+    assert data[:base][:total_expenses]
+  end
+
+  def test_scenario_comparison_hash_metrics_with_date_override
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    # Test hash metrics with date range override
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [
+        :net_income,
+        {
+          variable: :total_revenue,
+          start_date: "2024-01-01",
+          end_date: "2024-06-30",
+          label: "H1 Revenue",
+          key: :h1_revenue
+        },
+        {
+          variable: :total_revenue,
+          start_date: "2024-07-01",
+          end_date: "2024-12-31",
+          label: "H2 Revenue",
+          key: :h2_revenue
+        }
+      ]
+    )
+
+    data = comparison.generate
+
+    # Verify different keys for same variable with different date ranges
+    assert data[:base][:net_income]
+    assert data[:base][:h1_revenue]
+    assert data[:base][:h2_revenue]
+  end
+
+  def test_scenario_comparison_hash_metrics_with_period_name
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    # Test period_name for automatic key/label generation
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [
+        {
+          variable: :total_revenue,
+          period_name: "Q1",
+          start_date: "2024-01-01",
+          end_date: "2024-03-31"
+        },
+        {
+          variable: :total_revenue,
+          period_name: "Q2",
+          start_date: "2024-04-01",
+          end_date: "2024-06-30"
+        }
+      ]
+    )
+
+    data = comparison.generate
+
+    # period_name generates key like :total_revenue_q1
+    normalized = data[:metadata][:normalized_metrics]
+    assert_equal :total_revenue_q1, normalized[0][:key]
+    assert_equal :total_revenue_q2, normalized[1][:key]
+    assert_equal "Total Revenue (Q1)", normalized[0][:label]
+    assert_equal "Total Revenue (Q2)", normalized[1][:label]
+  end
+
+  def test_scenario_comparison_normalized_metrics_accessor
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [:net_income, { variable: :total_revenue, label: "Revenue" }]
+    )
+
+    # Test normalized_metrics accessor before generate
+    normalized = comparison.normalized_metrics
+    assert_equal 2, normalized.length
+    assert_equal :net_income, normalized[0][:variable]
+    assert_equal :total_revenue, normalized[1][:variable]
+    assert_equal "Revenue", normalized[1][:label]
+  end
+
+  def test_scenario_comparison_invalid_metric_format
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    # Hash without :variable key should raise error
+    assert_raises(ArgumentError) do
+      FinIt::Reports::ScenarioComparison.new(
+        @model,
+        scenarios: { growth: growth_model },
+        start_date: @start_date,
+        end_date: @end_date,
+        metrics: [{ label: "Invalid" }]  # Missing :variable key
+      )
+    end
+  end
+
+  def test_scenario_comparison_hash_metrics_format_option
+    @model.generate_transactions(@end_date)
+
+    growth_model = @model.with_plan(:growth_scenario)
+    growth_model.generate_transactions(@end_date)
+
+    comparison = FinIt::Reports::ScenarioComparison.new(
+      @model,
+      scenarios: { growth: growth_model },
+      start_date: @start_date,
+      end_date: @end_date,
+      metrics: [
+        { variable: :net_income, format: :currency },
+        { variable: :total_revenue, format: :number }
+      ]
+    )
+
+    normalized = comparison.normalized_metrics
+    assert_equal :currency, normalized[0][:format]
+    assert_equal :number, normalized[1][:format]
+  end
+end

data/test/scripts/generate_demo_reports.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+require "fin_it"
+require "date"
+
+model = FinIt.define(default_currency: "USD") do
+  config do
+    default_currency "USD"
+    start_date 2026
+  end
+
+  account :operating_cash do
+    type :asset
+    currency "USD"
+    opening_balance 100_000
+  end
+
+  category :income, type: :income do
+    variable :product_sales, currency: "USD", frequency: :monthly, account: :operating_cash do
+      value 45_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+  end
+
+  category :expenses, type: :expense do
+    variable :team_payroll, currency: "USD", frequency: :monthly, account: :operating_cash do
+      value 20_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+
+    variable :cloud_infrastructure, currency: "USD", frequency: :monthly, account: :operating_cash do
+      value 6_500, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+  end
+end
+
+report = FinIt::Reports::IncomeStatement.new(
+  model,
+  start_date: Date.new(2026, 1, 1),
+  end_date: Date.new(2026, 12, 31),
+  output_currency: "USD"
+)
+
+puts "Demo Income Statement (Fictional)"
+puts "=" * 80
+report.output(FinIt::Outputs::ConsoleOutput)

data/test/scripts/startup_saas_demo.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+require "fin_it"
+require "date"
+
+model = FinIt.define(default_currency: "USD") do
+  config do
+    default_currency "USD"
+    start_date 2026
+  end
+
+  account :cash do
+    type :asset
+    currency "USD"
+    opening_balance 250_000
+  end
+
+  category :income, type: :income do
+    variable :new_mrr, currency: "USD", frequency: :monthly, account: :cash do
+      value 35_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+
+    variable :expansion_mrr, currency: "USD", frequency: :monthly, account: :cash do
+      value 7_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+  end
+
+  category :expenses, type: :expense do
+    variable :engineering_payroll, currency: "USD", frequency: :monthly, account: :cash do
+      value 22_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+
+    variable :sales_marketing, currency: "USD", frequency: :monthly, account: :cash do
+      value 9_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+  end
+end
+
+model.generate_transactions(Date.new(2026, 12, 31))
+
+income_statement = FinIt::Reports::IncomeStatement.new(
+  model,
+  start_date: Date.new(2026, 1, 1),
+  end_date: Date.new(2026, 12, 31),
+  output_currency: "USD"
+)
+
+balance_sheet = FinIt::Reports::BalanceSheet.new(
+  model,
+  start_date: Date.new(2026, 1, 1),
+  end_date: Date.new(2026, 12, 31),
+  output_currency: "USD"
+)
+
+puts "Fictional SaaS Demo"
+puts "=" * 80
+income_statement.output(FinIt::Outputs::ConsoleOutput)
+puts
+balance_sheet.output(FinIt::Outputs::ConsoleOutput)

data/test/test_helper.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "fin_it"
+require "minitest/autorun"
+require "date"
+require "stringio"
+
+# Helper to suppress output during tests
+module OutputSuppression
+  def suppress_output
+    original_stdout = $stdout
+    $stdout = StringIO.new
+    yield
+  ensure
+    $stdout = original_stdout
+  end
+end
+
+# Include in all test classes
+class Minitest::Test
+  include OutputSuppression
+end
+

data/test/verify_accounting_equation.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/fin_it'
+require 'date'
+
+model = FinIt.define(default_currency: 'USD') do
+  config { start_date 2024 }
+  
+  account :checking do
+    type :asset
+    currency 'USD'
+    opening_balance 30_000
+  end
+  
+  account :mortgage do
+    type :liability
+    currency 'USD'
+    opening_balance(-200_000)
+  end
+  
+  category :current_assets, type: :asset do
+    calculated :checking_balance, formula: '0', account: :checking
+  end
+  
+  category :long_term_liabilities, type: :liability do
+    calculated :mortgage_balance, formula: '0', account: :mortgage
+  end
+  
+  category :equity, type: :equity do
+    calculated :equity_balance, formula: '0', account: :equity
+  end
+  
+  category :interest_expense, type: :expense do
+    calculated :mortgage_interest, formula: '0', account: :equity
+  end
+  
+  define_model :mortgage_payment do
+    variable :principal
+    variable :rate
+    
+    calculation do |date, context|
+      principal = context[:principal] || 200_000
+      rate = (context[:rate] || 0.035) / 12.0
+      interest = principal * rate
+      principal_payment = 1000 - interest
+      
+      [
+        { amount: principal_payment, debit_account: :mortgage, credit_account: :checking },
+        { amount: interest, debit_account: :equity, credit_account: :checking }
+      ]
+    end
+  end
+  
+  mortgage_payment do
+    start_date '2024-06-01'
+    principal 200_000
+    rate 0.035
+  end
+end
+
+model.generate_transactions(Date.new(2024, 12, 31))
+
+puts '=' * 80
+puts 'ACCOUNTING EQUATION VERIFICATION (A = L + E)'
+puts '=' * 80
+puts
+
+(1..12).each do |month|
+  month_end = Date.new(2024, month, -1)
+  assets = model.account_balance(:checking, as_of_date: month_end)
+  liabilities_raw = model.account_balance(:mortgage, as_of_date: month_end)
+  equity_raw = model.account_balance(:equity, as_of_date: month_end)
+  
+  # Liabilities are stored as negative, so convert to positive for equation
+  liabilities = liabilities_raw.abs
+  equity = equity_raw
+  
+  total_liab_equity = liabilities + equity
+  difference = (assets - total_liab_equity).abs
+  
+  status = difference < 0.01 ? 'BALANCED' : 'NOT BALANCED'
+  puts "#{month_end.strftime('%b %Y')}:"
+  puts "  Assets:      $#{assets.round(2)}"
+  puts "  Liabilities: $#{liabilities.round(2)} (stored as: $#{liabilities_raw.round(2)})"
+  puts "  Equity:      $#{equity.round(2)}"
+  puts "  L + E:       $#{total_liab_equity.round(2)}"
+  puts "  Difference:  $#{difference.round(2)} [#{status}]"
+  puts
+end
+