fin_it 0.1.0

data/lib/fin_it/payment_schedule.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'ice_cube'
+
+module FinIt
+  # Handles payment date recurrence logic using ice_cube
+  class PaymentSchedule
+    attr_reader :schedule, :start_date, :end_date
+
+    def initialize(frequency:, payment_schedule: {}, start_date: nil, end_date: nil)
+      @frequency = frequency
+      @payment_schedule = payment_schedule
+      @start_date = parse_date(start_date)
+      @end_date = parse_date(end_date)
+      @schedule = build_schedule
+    end
+
+    # Check if a given date is a payment date
+    def payment_date?(date)
+      date = parse_date(date)
+      return false if date.nil?
+      return false if @start_date && date < @start_date
+      return false if @end_date && date > @end_date
+      
+      @schedule.occurs_on?(date)
+    end
+
+    # Get the next payment date after a given date
+    def next_payment_date(after_date = nil)
+      after_date ||= Date.today
+      after_date = parse_date(after_date)
+      
+      occurrences = @schedule.occurrences(after_date + 1)
+      occurrences.first
+    end
+
+    # Get all payment dates in a range
+    def payment_dates_in_range(start_date, end_date)
+      start_date = parse_date(start_date)
+      end_date = parse_date(end_date)
+      
+      @schedule.occurrences_between(start_date, end_date)
+    end
+
+    private
+
+    def build_schedule
+      schedule = IceCube::Schedule.new(@start_date || Date.today)
+      
+      case @frequency
+      when :daily
+        schedule.add_recurrence_rule IceCube::Rule.daily
+      when :weekly
+        day_of_week = @payment_schedule[:day_of_week] || 1 # Monday by default
+        schedule.add_recurrence_rule IceCube::Rule.weekly.day(day_of_week)
+      when :monthly
+        day_of_month = @payment_schedule[:day_of_month] || 1
+        if day_of_month == -1 || day_of_month == :last
+          # Last day of month
+          schedule.add_recurrence_rule IceCube::Rule.monthly.day_of_month(-1)
+        else
+          schedule.add_recurrence_rule IceCube::Rule.monthly.day_of_month(day_of_month)
+        end
+      when :quarterly
+        months = @payment_schedule[:months] || [1, 4, 7, 10]
+        day = @payment_schedule[:day] || 1
+        months.each do |month|
+          schedule.add_recurrence_rule IceCube::Rule.yearly.month_of_year(month).day_of_month(day)
+        end
+      when :annual, :yearly
+        month = @payment_schedule[:month] || 1
+        day = @payment_schedule[:day] || 1
+        schedule.add_recurrence_rule IceCube::Rule.yearly.month_of_year(month).day_of_month(day)
+      else
+        # Custom schedule rule provided
+        if @payment_schedule[:schedule_rule]
+          schedule.add_recurrence_rule @payment_schedule[:schedule_rule]
+        else
+          # Default to monthly if frequency not recognized
+          schedule.add_recurrence_rule IceCube::Rule.monthly.day_of_month(1)
+        end
+      end
+      
+      # Apply end date if specified - add to recurrence rules
+      if @end_date
+        # Update all recurrence rules to have an end date
+        schedule.recurrence_rules.each do |rule|
+          # Check if rule already has an until time set
+          has_until = rule.respond_to?(:until_time) && rule.until_time
+          rule.until(@end_date) unless has_until
+        end
+      end
+      
+      schedule
+    end
+
+    def parse_date(date)
+      return nil if date.nil?
+      return date if date.is_a?(Date)
+      
+      case date
+      when String
+        Date.parse(date)
+      when Time
+        date.to_date
+      else
+        date
+      end
+    end
+  end
+end
+

data/lib/fin_it/plan.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module FinIt
+  # Represents a scenario plan that can modify a financial model's variables
+  # Plans are applied to create isolated copies of models for what-if analysis
+  class Plan
+    attr_reader :name, :description, :overrides, :start_date, :end_date
+
+    def initialize(name, description: nil, start_date: nil, end_date: nil)
+      @name = name
+      @description = description
+      @start_date = parse_date(start_date)
+      @end_date = parse_date(end_date)
+      @overrides = []
+    end
+
+    # Override a variable with a new value
+    # @param variable_name [Symbol] The variable to override
+    # @param value [Numeric, Money] The new value
+    # @param start_date [Date, String, nil] When override starts
+    # @param end_date [Date, String, nil] When override ends
+    def set(variable_name, value, start_date: nil, end_date: nil)
+      @overrides << {
+        type: :set,
+        variable: variable_name.to_sym,
+        value: value,
+        start_date: parse_date(start_date),
+        end_date: parse_date(end_date)
+      }
+      self
+    end
+
+    # Multiply variable by factor
+    # @param variable_name [Symbol] The variable to scale
+    # @param factor [Numeric] The multiplication factor (e.g., 1.10 for +10%)
+    # @param start_date [Date, String, nil] When scaling starts
+    # @param end_date [Date, String, nil] When scaling ends
+    def scale(variable_name, factor, start_date: nil, end_date: nil)
+      @overrides << {
+        type: :scale,
+        variable: variable_name.to_sym,
+        factor: factor,
+        start_date: parse_date(start_date),
+        end_date: parse_date(end_date)
+      }
+      self
+    end
+
+    # Add/subtract amount from variable
+    # @param variable_name [Symbol] The variable to adjust
+    # @param amount [Numeric] The amount to add (negative to subtract)
+    # @param start_date [Date, String, nil] When adjustment starts
+    # @param end_date [Date, String, nil] When adjustment ends
+    def adjust(variable_name, amount, start_date: nil, end_date: nil)
+      @overrides << {
+        type: :adjust,
+        variable: variable_name.to_sym,
+        amount: amount,
+        start_date: parse_date(start_date),
+        end_date: parse_date(end_date)
+      }
+      self
+    end
+
+    # Replace formula for calculated variable
+    # @param variable_name [Symbol] The calculated variable
+    # @param new_formula [String] The new formula
+    # @param start_date [Date, String, nil] When formula starts
+    # @param end_date [Date, String, nil] When formula ends
+    def formula(variable_name, new_formula, start_date: nil, end_date: nil)
+      @overrides << {
+        type: :formula,
+        variable: variable_name.to_sym,
+        formula: new_formula,
+        start_date: parse_date(start_date),
+        end_date: parse_date(end_date)
+      }
+      self
+    end
+
+    # Add a new variable to the model
+    # @param name [Symbol] Variable name
+    # @param category [Symbol] Category to add variable to
+    # @param currency [String, nil] Currency code
+    # @param block [Block] Variable definition block
+    def add_variable(name, category:, currency: nil, &block)
+      @overrides << {
+        type: :add_variable,
+        name: name.to_sym,
+        category: category.to_sym,
+        currency: currency,
+        block: block
+      }
+      self
+    end
+
+    # Add a new calculated variable to the model
+    # @param name [Symbol] Variable name
+    # @param category [Symbol] Category to add to
+    # @param formula [String] The formula
+    # @param options [Hash] Additional options (start_date, end_date, etc.)
+    def add_calculated(name, category:, formula:, **options)
+      @overrides << {
+        type: :add_calculated,
+        name: name.to_sym,
+        category: category.to_sym,
+        formula: formula,
+        options: options
+      }
+      self
+    end
+
+    # Set account opening balance
+    # @param account_name [Symbol] The account name
+    # @param amount [Numeric] The new opening balance
+    def set_opening_balance(account_name, amount)
+      @overrides << {
+        type: :opening_balance,
+        account: account_name.to_sym,
+        amount: amount
+      }
+      self
+    end
+
+    # Create a copy of this plan
+    def dup
+      new_plan = Plan.new(@name, description: @description,
+                          start_date: @start_date, end_date: @end_date)
+      @overrides.each do |override|
+        new_plan.instance_variable_get(:@overrides) << override.dup
+      end
+      new_plan
+    end
+
+    private
+
+    def parse_date(date)
+      return nil if date.nil?
+      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