fin_it 0.1.0

data/lib/fin_it/dsl/model_template_builder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FinIt
+  module DSL
+    # Builder for model templates
+    class ModelTemplateBuilder
+      def initialize(template)
+        @template = template
+      end
+      
+      def variable(name)
+        @template.add_variable(name)
+      end
+      
+      def default_debit_accounts(accounts)
+        @template.set_default_debit_accounts(accounts)
+      end
+      
+      def default_credit_accounts(accounts)
+        @template.set_default_credit_accounts(accounts)
+      end
+      
+      def calculation(&block)
+        @template.set_calculation(&block)
+      end
+    end
+  end
+end
+

data/lib/fin_it/dsl/plan_builder.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FinIt
+  module DSL
+    # DSL builder for defining plans within FinIt.define
+    class PlanBuilder
+      def initialize(name, description: nil, start_date: nil, end_date: nil)
+        @plan = Plan.new(name, description: description, start_date: start_date, end_date: end_date)
+      end
+
+      # Override a variable with a new value
+      def set(variable_name, value, start_date: nil, end_date: nil)
+        @plan.set(variable_name, value, start_date: start_date, end_date: end_date)
+      end
+
+      # Multiply variable by factor
+      def scale(variable_name, factor, start_date: nil, end_date: nil)
+        @plan.scale(variable_name, factor, start_date: start_date, end_date: end_date)
+      end
+
+      # Add/subtract from variable
+      def adjust(variable_name, amount, start_date: nil, end_date: nil)
+        @plan.adjust(variable_name, amount, start_date: start_date, end_date: end_date)
+      end
+
+      # Replace formula for calculated variable
+      def formula(variable_name, new_formula, start_date: nil, end_date: nil)
+        @plan.formula(variable_name, new_formula, start_date: start_date, end_date: end_date)
+      end
+
+      # Add a new variable
+      def add_variable(name, category:, currency: nil, &block)
+        @plan.add_variable(name, category: category, currency: currency, &block)
+      end
+
+      # Add a new calculated variable
+      def add_calculated(name, category:, formula:, **options)
+        @plan.add_calculated(name, category: category, formula: formula, **options)
+      end
+
+      # Set account opening balance
+      def set_opening_balance(account_name, amount)
+        @plan.set_opening_balance(account_name, amount)
+      end
+
+      # Build and return the plan
+      def build
+        @plan
+      end
+    end
+  end
+end

data/lib/fin_it/dsl/project_inheritance_resolver.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module FinIt
+  module DSL
+    # Resolves project inheritance for calculated variables based on their dependencies
+    class ProjectInheritanceResolver
+      def initialize(calculator)
+        @calculator = calculator
+      end
+      
+      # Resolve project tag from dependencies
+      # Current logic: If ANY dependency has a project tag, inherit that project
+      # Future: Can be extended to support more complex logic (priority, intersection, etc.)
+      def resolve_project(dependencies, projects_map = nil)
+        return nil if dependencies.empty?
+        
+        # Build projects map if not provided
+        projects_map ||= build_projects_map(dependencies)
+        
+        # Find first dependency with a project tag
+        dependencies.each do |dep_name|
+          # Try both symbol and string keys
+          project = projects_map[dep_name] || projects_map[dep_name.to_sym] || projects_map[dep_name.to_s]
+          return project if project
+        end
+        
+        nil
+      end
+      
+      private
+      
+      def build_projects_map(dependencies)
+        map = {}
+        dependencies.each do |dep_name|
+          project = @calculator.get_variable_project(dep_name)
+          # Store with both symbol and string keys for flexibility
+          map[dep_name] = project
+          map[dep_name.to_sym] = project if dep_name.is_a?(String)
+          map[dep_name.to_s] = project if dep_name.is_a?(Symbol)
+        end
+        map
+      end
+    end
+  end
+end
+

data/lib/fin_it/dsl/variable_builder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FinIt
+  module DSL
+    # Builder for variable definitions
+    class VariableBuilder
+      def initialize(name, calculator, default_currency = nil, frequency: :annual, account: nil, project: nil)
+        @name = name
+        @calculator = calculator
+        @default_currency = default_currency  # Can be nil for drivers
+        @frequency = frequency
+        @account = account
+        @project = project
+      end
+
+      def value(amount, start_date: nil, end_date: nil)
+        @calculator.define_variable(@name, amount, 
+          currency: @default_currency,  # Will be nil for drivers
+          frequency: @frequency,
+          start_date: start_date, 
+          end_date: end_date,
+          account: @account,
+          project: @project
+        )
+      end
+
+      def description(text)
+        # Store description metadata
+      end
+
+      def unit(unit_name)
+        # Store unit metadata
+      end
+
+      def frequency(freq)
+        # Store frequency metadata
+      end
+    end
+  end
+end
+

data/lib/fin_it/dsl.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'dsl/model_builder'
+require_relative 'financial_model'
+
+module FinIt
+  # Main DSL entry point
+  def self.define(default_currency: 'USD', &block)
+    builder = DSL::ModelBuilder.new(default_currency: default_currency)
+    builder.instance_eval(&block)
+    builder.build
+  end
+end

data/lib/fin_it/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module FinIt
+  class Engine < ::Rails::Engine
+    isolate_namespace FinIt
+
+    config.generators do |g|
+      g.test_framework :minitest
+      g.fixture_replacement :factory_bot
+    end
+  end
+end
+

data/lib/fin_it/financial_model/account_balances.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'money'
+
+module FinIt
+  class FinancialModel
+    # Account balance calculations (cumulative balances up to a date)
+    module AccountBalances
+      # Get account balance at a specific date (cumulative balance)
+      def account_balance(account_name, as_of_date:)
+        account = @accounts[account_name]
+        return 0 unless account
+        
+        as_of_date = parse_date(as_of_date)
+        validate_date!(as_of_date)
+        
+        # Generate transactions up to as_of_date if not already generated
+        @transaction_generator.generate_transactions(as_of_date)
+        
+        # Start with opening balance as Money object (all values are stored as positive)
+        balance = Money.new((account.opening_balance.to_f * 100).to_i, account.currency)
+        
+        # Get all transactions affecting this account up to as_of_date
+        # Exclude opening balance transactions - they record initial state, not changes
+        account_transactions = @transaction_generator.transactions(
+          date_range: { start: @start_date, end: as_of_date },
+          account: account_name
+        ).reject { |t| t[:variable] == :opening_balance }
+        
+        # Apply transactions to balance using Money objects for precision
+        # Account type determines how debits/credits affect balance:
+        # All accounts store positive values. The accounting equation is: Assets = Liabilities + Equity
+        # - Assets: Debits increase (balance +=), Credits decrease (balance -=)
+        # - Liabilities: Debits decrease (balance -=), Credits increase (balance +=)
+        # - Equity: Debits decrease (balance -=), Credits increase (balance +=)
+        account_transactions.each do |transaction|
+          # Convert transaction amount to account currency if needed
+          transaction_amount = transaction[:amount]
+          if transaction_amount.is_a?(Money)
+            # Convert to account currency if different
+            if transaction_amount.currency.iso_code != account.currency
+              transaction_amount = transaction_amount.exchange_to(account.currency)
+            end
+          else
+            # Legacy: convert float to Money (shouldn't happen after refactoring)
+            transaction_amount = Money.new((transaction_amount.to_f * 100).to_i, account.currency)
+          end
+          
+          if transaction[:debit_account] == account_name
+            # Debit affects balance based on account type
+            if account.type == :asset
+              balance += transaction_amount  # Debits increase assets
+            else  # liability or equity
+              balance -= transaction_amount  # Debits decrease liabilities/equity
+            end
+          elsif transaction[:credit_account] == account_name
+            # Credit affects balance based on account type
+            if account.type == :asset
+              balance -= transaction_amount  # Credits decrease assets
+            else  # liability or equity
+              balance += transaction_amount  # Credits increase liabilities/equity
+            end
+          end
+        end
+        
+        # Return as float for backward compatibility (Money object would be better but breaks API)
+        balance.to_f
+      end
+      
+      # Sum balances for multiple accounts (for balance sheets)
+      def accounts_total_balance(account_names, as_of_date:, output_currency: nil)
+        output_currency ||= @config[:default_currency]
+        as_of_date = parse_date(as_of_date)
+        validate_date!(as_of_date)
+        
+        total = Money.new(0, output_currency)
+        
+        Array(account_names).each do |account_name|
+          account = @accounts[account_name]
+          next unless account
+          
+          # Use account balance at as_of_date
+          balance = account_balance(account_name, as_of_date: as_of_date)
+          account_money = Money.new((balance * 100).to_i, account.currency)
+          
+          # Convert to output currency if needed
+          if account_money.currency.iso_code != output_currency
+            account_money = account_money.exchange_to(output_currency)
+          end
+          
+          total += account_money
+        end
+        
+        total.to_f
+      end
+    end
+  end
+end
+

data/lib/fin_it/financial_model/account_hierarchy.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module FinIt
+  class FinancialModel
+    # Account hierarchy query methods
+    module AccountHierarchy
+      # Get account hierarchy (account with children)
+      def account_hierarchy(account_name)
+        account = @accounts[account_name]
+        return nil unless account
+        account
+      end
+
+      # Find account by hierarchical path (e.g., [:cost_of_goods_sold, :shrimp_cost_regular])
+      def find_account_by_path(path_array)
+        return nil if path_array.nil? || path_array.empty?
+        
+        path_array = path_array.map(&:to_sym)
+        current_account = @accounts[path_array.first]
+        return nil unless current_account
+        
+        path_array[1..-1].each do |name|
+          current_account = current_account.children.find { |child| child.name == name }
+          return nil unless current_account
+        end
+        
+        current_account
+      end
+
+      # Get direct children of an account
+      def account_children(account_name)
+        account = @accounts[account_name]
+        return [] unless account
+        account.children
+      end
+
+      # Get all descendants of an account recursively
+      def account_descendants(account_name)
+        account = @accounts[account_name]
+        return [] unless account
+        account.descendants
+      end
+
+      # Get account for a category (if category-to-account mapping exists)
+      def category_account(category)
+        # Use category_accounts mapping if available
+        return @category_accounts[category] if @category_accounts && @category_accounts[category]
+        
+        # Fallback: try to find account by category name
+        account_name = category.name.to_sym
+        return @accounts[account_name] if @accounts.key?(account_name)
+        
+        # If not found, search for account with matching name
+        # This handles cases where category and account have same name
+        nil
+      end
+
+      # Get category for an account (reverse lookup)
+      def account_category(account_name)
+        account = @accounts[account_name]
+        return nil unless account
+        
+        # Search categories for one matching account name
+        @categories.find { |cat| cat.name == account.name }
+      end
+
+      # Calculate total for account including all children
+      # For income/expense: uses period flow
+      # For asset/liability/equity: uses balance
+      def account_total(account_name, start_date, end_date, use_balance: false, output_currency: nil)
+        account = @accounts[account_name]
+        return 0 unless account
+        
+        output_currency ||= @config[:default_currency]
+        start_date = parse_date(start_date)
+        end_date = parse_date(end_date)
+        
+        # If account has children, sum children totals
+        if account.children.any?
+          total = account.children.sum do |child|
+            account_total(child.name, start_date, end_date, use_balance: use_balance, output_currency: output_currency)
+          end
+          
+          # Convert to output currency if needed
+          if account.currency != output_currency
+            total_money = Money.new((total * 100).to_i, account.currency)
+            total = @calculator.convert_currency(total_money, output_currency).to_f
+          end
+          
+          total
+        else
+          # Leaf account: use its own value
+          if use_balance
+            balance = account_balance(account_name, as_of_date: end_date)
+            # Convert to output currency if needed
+            if account.currency != output_currency
+              balance_money = Money.new((balance * 100).to_i, account.currency)
+              balance = @calculator.convert_currency(balance_money, output_currency).to_f
+            end
+            balance
+          else
+            flow = account_period_flow(account_name, start_date, end_date)
+            # Convert to output currency if needed
+            if account.currency != output_currency
+              flow_money = Money.new((flow * 100).to_i, account.currency)
+              flow = @calculator.convert_currency(flow_money, output_currency).to_f
+            end
+            flow
+          end
+        end
+      end
+
+      # Get period flow for account including all children
+      def account_period_flow_with_children(account_name, start_date, end_date, output_currency: nil)
+        account_total(account_name, start_date, end_date, use_balance: false, output_currency: output_currency)
+      end
+
+      # Get balance for account including all children
+      def account_balance_with_children(account_name, as_of_date, output_currency: nil)
+        account_total(account_name, as_of_date, as_of_date, use_balance: true, output_currency: output_currency)
+      end
+
+      # Calculate category total via account hierarchy
+      def category_total_via_account(category, start_date, end_date, period_type: nil, output_currency: nil, filters: {}, use_balance: false)
+        # Get account for category
+        account = category_account(category)
+        
+        if account
+          # Use account hierarchy for calculation
+          # If filters are applied, we need to filter by project at the account level
+          # For now, use the account total (filtering by project would require transaction-level filtering)
+          total = account_total(account.name, start_date, end_date, use_balance: use_balance, output_currency: output_currency)
+          
+          # Apply project filter if needed (filter transactions by variable project)
+          if filters[:project] && account.children.any?
+            # Filter children accounts by their variable's project
+            filtered_total = account.children.sum do |child_account|
+              # Check if child account's variable matches project filter
+              child_var = category.variables.find { |v| v[:name] == child_account.name }
+              if child_var && variable_matches_project?(child_var, filters[:project])
+                account_total(child_account.name, start_date, end_date, use_balance: use_balance, output_currency: output_currency)
+              else
+                0
+              end
+            end
+            return filtered_total
+          end
+          
+          total
+        else
+          # Fallback to category-based calculation (backward compatibility)
+          category_total_for_period(category, start_date, end_date, period_type: period_type, output_currency: output_currency, filters: filters)
+        end
+      end
+    end
+  end
+end
+

data/lib/fin_it/financial_model/category_values.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'money'
+
+module FinIt
+  class FinancialModel
+    # Category variable value calculations
+    module CategoryValues
+      # Calculate total for a category and its descendants for a period
+      # Handles account-based variables using account_period_flow() or account_balance()
+      # Handles non-account variables using calculator.calculate() with period_type
+      # Category totals are calculated as: sum of children category totals (if children exist), 
+      # otherwise sum of direct variable values
+      # With hierarchical accounts: prefers account-based calculation if category has an account
+      def category_total_for_period(category, start_date, end_date, period_type: nil, output_currency: nil, filters: {}, use_account_transactions_only: false)
+        output_currency ||= @config[:default_currency]
+        period_type ||= determine_period_type(start_date, end_date)
+        
+        start_date = parse_date(start_date)
+        end_date = parse_date(end_date)
+        # Don't validate dates here - allow reports to query any date range
+        # Use max of start_date and model start_date for actual calculations
+        start_date = [start_date, @start_date].max
+        end_date = [end_date, @start_date].max
+        
+        # Try account-based calculation first (hierarchical accounts)
+        # Use AccountHierarchy methods via self (since both modules are included in FinancialModel)
+        if respond_to?(:category_account)
+          category_account = category_account(category)
+          if category_account
+            use_balance = [:asset, :liability, :equity].include?(category.type)
+            return category_total_via_account(category, start_date, end_date, 
+              period_type: period_type, output_currency: output_currency, 
+              filters: filters, use_balance: use_balance)
+          end
+        end
+        
+        # Fallback to variable-based calculation (backward compatibility)
+        # If bypassing category hierarchy, calculate only from direct account transactions
+        if use_account_transactions_only
+          # Filter variables by project if filter is set
+          variables = category.variables
+          if filters[:project]
+            variables = variables.select { |var| variable_matches_project?(var, filters[:project]) }
+          end
+          
+          return variables.sum do |var|
+            category_variable_value(var, end_date, period_type: period_type, output_currency: output_currency, category_type: category.type, start_date: start_date)
+          end
+        end
+        
+        # Category total calculation logic:
+        # If category has children → total = sum of children category totals (recursive)
+        # If category has no children → total = sum of direct variable values
+        # This prevents double counting (children totals already include their variables)
+        
+        if category.children.any?
+          # Has children: sum of children category totals
+          category.children.sum do |child|
+            category_total_for_period(child, start_date, end_date, period_type: period_type, output_currency: output_currency, filters: filters, use_account_transactions_only: false)
+          end
+        else
+          # No children: sum of direct variable values
+          variables = category.variables
+          if filters[:project]
+            variables = variables.select { |var| variable_matches_project?(var, filters[:project]) }
+          end
+          
+          variables.sum do |var|
+            category_variable_value(var, end_date, period_type: period_type, output_currency: output_currency, category_type: category.type, start_date: start_date)
+          end
+        end
+      end
+      
+      # Get value for a single variable in a category context
+      # Checks if variable maps to account, uses appropriate method
+      # For income/expense: uses account_period_flow() (period flow, not cumulative)
+      # For balance sheet: uses account_balance() (cumulative balance)
+      def category_variable_value(var_data, date, period_type: :annual, output_currency: nil, category_type: nil, start_date: nil)
+        output_currency ||= @config[:default_currency]
+        date = parse_date(date)
+        # Don't validate date here - allow reports to query any date range
+        # Validation happens when generating transactions
+        
+        # Check if variable maps to account
+        account_name = var_data[:account] || var_data[:debit_account] || var_data[:credit_account]
+        
+        if account_name && @accounts[account_name]
+          # Use account-based calculation
+          account = @accounts[account_name]
+          
+          # For income statements: use account_period_flow
+          # For balance sheets: use account_balance
+          if category_type && [:income, :expense].include?(category_type)
+            # Income/expense categories: use period flow FOR THIS SPECIFIC VARIABLE
+            # Use provided start_date or model start_date as fallback
+            period_start = start_date || @start_date
+            period_start = parse_date(period_start)
+            # Don't validate period_start - use max of period_start and model start_date
+            period_start = [period_start, @start_date].max
+            
+            # Filter transactions by variable name to get flow for this specific variable only
+            # Use transaction-based flow directly - no overrides for quarterly fees
+            flow = account_period_flow(account_name, period_start, date, variable: var_data[:name])
+            
+            # For income categories: positive flow is income
+            # For expense categories: flow direction depends on account type
+            # - Asset accounts: Credit (negative flow) = expense, so use -flow
+            # - Liability accounts: Credit (positive flow) = expense, so use flow
+            # - Equity accounts: Debit (negative flow) = expense, so use -flow
+            if category_type == :income
+              flow_value = flow > 0 ? flow : 0
+            elsif category_type == :expense
+              if account.type == :liability
+                # Liability accounts: credit = positive flow = expense
+                flow_value = flow > 0 ? flow : 0
+              else
+                # Asset/Equity accounts: credit/debit = negative flow = expense
+                flow_value = flow < 0 ? -flow : 0
+              end
+            else
+              flow_value = flow
+            end
+            
+            # Convert to output currency if needed
+            if account.currency != output_currency
+              flow_money = Money.new((flow_value * 100).to_i, account.currency)
+              flow_value = @calculator.convert_currency(flow_money, output_currency).to_f
+            end
+            
+            flow_value
+          else
+            # Balance sheet categories: use account balance
+            balance = account_balance(account_name, as_of_date: date)
+            
+            # Convert to output currency if needed
+            if account.currency != output_currency
+              balance_money = Money.new((balance * 100).to_i, account.currency)
+              balance = @calculator.convert_currency(balance_money, output_currency).to_f
+            end
+            
+            balance
+          end
+        else
+          # Use standard variable calculation (no account mapping)
+          # Calculator already handles period scaling via period_type parameter
+          var_value = @calculator.calculate(
+            var_data[:name],
+            date: date,
+            output_currency: output_currency,
+            period_type: period_type
+          )
+          
+          var_value.is_a?(Money) ? var_value.to_f : (var_value || 0)
+        end
+      end
+      
+      # Sum flows/balances for multiple accounts
+      # For income statements: uses account_period_flow() for each account
+      # For balance sheets: uses account_balance() for each account
+      def accounts_total_for_period(account_names, start_date, end_date, account_type: nil, output_currency: nil, use_balance: false)
+        output_currency ||= @config[:default_currency]
+        start_date = parse_date(start_date)
+        end_date = parse_date(end_date)
+        validate_date!(start_date)
+        validate_date!(end_date)
+        
+        if use_balance
+          # For balance sheets: use account balance at end_date
+          accounts_total_balance(account_names, as_of_date: end_date, output_currency: output_currency)
+        else
+          # For income statements: use account period flow
+          accounts_total_flow(account_names, start_date, end_date, output_currency: output_currency)
+        end
+      end
+    end
+  end
+end
+

data/lib/fin_it/financial_model/currency_helpers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module FinIt
+  class FinancialModel
+    # Currency conversion and scaling utilities
+    # Note: Period scaling is handled by Calculator via TemporalValue#value_at
+    # This module is kept for future currency-related helper methods
+    module CurrencyHelpers
+      # Placeholder for future currency helper methods
+      # Period scaling is handled by Calculator, not here
+    end
+  end
+end
+