fin_it 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59e004f074fbfaec9a9898cd16213992433339e63994579ba5ea8daa8cde0470
+  data.tar.gz: 37448fbcd255d8cc44bf36fedb6f4b522a6365c87cc5531c6c1e6528d42dda33
+SHA512:
+  metadata.gz: 24d9587217a55d4ee8bf370b24b2235ece9520ed9332ad3b8dbb69b7946691e181095dee2c0dea73c31e73647ab358976ce2df8e6cb99a48d7a436ba7d960073
+  data.tar.gz: c16eac875c5058a854fad9be3d40e0359dfc112fe87b8a3077772abdb72cb40ee2c0cdd47adb93d9b52cdc11b39396894db8a93e7417ac66fa554e21aa252e6b

data/ARCHITECTURE.md

@@ -0,0 +1,24 @@
+# Architecture
+
+## Core Layers
+
+- `lib/fin_it.rb`: entrypoint and component loading
+- `lib/fin_it/dsl/`: model definition DSL
+- `lib/fin_it/calculator.rb`: formula evaluation and variable calculation
+- `lib/fin_it/financial_model.rb`: runtime model orchestration
+- `lib/fin_it/reports/`: report builders
+- `lib/fin_it/outputs/`: output adapters (console and spreadsheet)
+
+## Data Flow
+
+1. DSL definitions build model components (accounts, categories, variables, formulas).
+2. Calculator resolves variable values and formulas by date/period.
+3. Transaction generator materializes accounting movements.
+4. Reports aggregate values into financial statements.
+5. Output adapters render result sets.
+
+## Extension Points
+
+- Add custom report builders under `lib/fin_it/reports`.
+- Add custom output formatters under `lib/fin_it/outputs`.
+- Use model templates and plans to compose reusable scenarios.

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0] - 2026-03-07
+
+- Public rebrand to `fin_it`.
+- API namespace updated to `FinIt`.
+- Private/sensitive scripts removed and replaced with fictional demos.
+- Added GitHub Actions for PR validation and guarded publish-on-master.
+- Added public-facing documentation set and project branding assets.

data/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+## Setup
+
+```bash
+bundle install
+```
+
+## Run test suite
+
+```bash
+bundle exec rake test
+```
+
+## Pull request checklist
+
+- Keep changes focused and documented.
+- Add or update tests for behavior changes.
+- Ensure CI is green.
+- Avoid committing private or customer data.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Growth Constant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/QUICKSTART.md

@@ -0,0 +1,56 @@
+# Quickstart
+
+## 1. Install
+
+```bash
+bundle add fin_it
+```
+
+## 2. Define a model
+
+```ruby
+require "fin_it"
+
+model = FinIt.define(default_currency: "USD") do
+  config { start_date "2026-01-01" }
+
+  account :operating_cash do
+    type :asset
+    currency "USD"
+    opening_balance 40_000
+  end
+
+  category :income, type: :income do
+    variable :consulting_revenue, currency: "USD", frequency: :monthly, account: :operating_cash do
+      value 22_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+  end
+
+  category :expenses, type: :expense do
+    variable :payroll, currency: "USD", frequency: :monthly, account: :operating_cash do
+      value 12_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+  end
+end
+```
+
+## 3. Generate reports
+
+```ruby
+require "date"
+
+income_statement = FinIt::Reports::IncomeStatement.new(
+  model,
+  start_date: Date.new(2026, 1, 1),
+  end_date: Date.new(2026, 12, 31),
+  output_currency: "USD"
+)
+
+income_statement.output(FinIt::Outputs::ConsoleOutput)
+```
+
+## 4. Run tests locally
+
+```bash
+bundle exec rake test
+```

data/README.md

@@ -0,0 +1,74 @@
+# fin_it
+
+![fin_it logo](assets/fin_it_logo.png)
+
+`fin_it` is a Ruby gem for scenario-based financial modeling, formula-driven calculations, and multi-format reporting.
+
+## Why fin_it
+
+- Define models with a Ruby DSL
+- Calculate values over time with period-aware logic
+- Build Income Statement, Balance Sheet, and Cash Flow outputs
+- Export to console and spreadsheet formats
+
+## Installation
+
+```ruby
+gem "fin_it"
+```
+
+## Quick Start
+
+```ruby
+require "fin_it"
+require "date"
+
+model = FinIt.define(default_currency: "USD") do
+  config do
+    start_date "2026-01-01"
+  end
+
+  account :cash do
+    type :asset
+    currency "USD"
+    opening_balance 25_000
+  end
+
+  category :income, type: :income do
+    variable :subscription_revenue, currency: "USD", frequency: :monthly, account: :cash do
+      value 18_000, start_date: "2026-01-01", end_date: "2026-12-31"
+    end
+  end
+
+  category :expenses, type: :expense do
+    variable :hosting_cost, currency: "USD", frequency: :monthly, account: :cash do
+      value 2_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"
+)
+
+report.output(FinIt::Outputs::ConsoleOutput)
+```
+
+## Documentation
+
+- [QUICKSTART.md](QUICKSTART.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)
+- [CHANGELOG.md](CHANGELOG.md)
+
+## Migration Note
+
+This project was rebranded from the previous internal package naming. Public API now uses `FinIt` and `require "fin_it"`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+desc "Run all Minitest tests (use TEST=path/to/test.rb to run specific file)"
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = if ENV["TEST"]
+    FileList[ENV["TEST"]]
+  else
+    FileList["test/**/*_test.rb"]
+  end
+  t.verbose = true
+end
+
+task default: :test
+
+desc "Run income statement generator"
+task :income_statement do
+  ruby "test/scripts/generate_demo_reports.rb"
+end

data/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately to `oss@growth-constant.com`.
+
+Include:
+
+- Impact summary
+- Reproduction steps
+- Affected versions
+- Suggested remediation (if available)
+
+Do not open a public issue for unpatched vulnerabilities.

data/lib/fin_it/account.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'money'
+
+module FinIt
+  # Represents a financial account (asset, liability, equity, income, or expense)
+  # All account balances are stored as positive values.
+  # The accounting equation is: Assets = Liabilities + Equity
+  # Accounts can be hierarchical (parent-child relationships)
+  class Account
+    attr_reader :name, :type, :currency, :opening_balance, :opening_balance_credit_account, :parent
+    attr_accessor :children
+
+    def initialize(name, type:, currency: 'USD', opening_balance: 0, opening_balance_credit_account: :equity, parent: nil)
+      @name = name
+      @type = type # :asset, :liability, :equity, :income, or :expense
+      @currency = currency
+      @opening_balance = opening_balance
+      @opening_balance_credit_account = opening_balance_credit_account
+      @parent = parent
+      @children = []
+      
+      validate!
+      
+      # Add self to parent's children if parent exists
+      if @parent
+        @parent.children << self unless @parent.children.include?(self)
+      end
+    end
+
+    # Get the full hierarchical path from root to this account
+    def path
+      if @parent
+        @parent.path + [@name]
+      else
+        [@name]
+      end
+    end
+
+    # Get the full hierarchical name (e.g., "cost_of_goods_sold.shrimp_cost_regular")
+    def full_name
+      path.join('.')
+    end
+
+    # Get all descendants recursively
+    def descendants
+      @children + @children.flat_map(&:descendants)
+    end
+
+    # Check if this account is a root account (no parent)
+    def root?
+      @parent.nil?
+    end
+
+    # Check if this account is a leaf account (no children)
+    def leaf?
+      @children.empty?
+    end
+
+    def to_h
+      {
+        name: @name,
+        type: @type,
+        currency: @currency,
+        opening_balance: @opening_balance,
+        opening_balance_credit_account: @opening_balance_credit_account,
+        parent: @parent&.name,
+        children: @children.map(&:name)
+      }
+    end
+
+    # Deep clone this account (without parent/children relationships)
+    def deep_clone
+      Account.new(
+        @name,
+        type: @type,
+        currency: @currency,
+        opening_balance: @opening_balance,
+        opening_balance_credit_account: @opening_balance_credit_account,
+        parent: nil  # Parent will be set up separately during model cloning
+      )
+    end
+
+    private
+
+    def validate!
+      valid_types = [:asset, :liability, :equity, :income, :expense]
+      unless valid_types.include?(@type)
+        raise ArgumentError, "Account type must be one of #{valid_types.join(', ')}, got #{@type}"
+      end
+
+      unless @name.is_a?(Symbol) || @name.is_a?(String)
+        raise ArgumentError, "Account name must be a Symbol or String"
+      end
+
+      # Validate parent-child type compatibility
+      if @parent
+        # Income/expense can be children of income/expense accounts
+        # Asset/liability/equity can be children of same type
+        if [:income, :expense].include?(@type)
+          unless [:income, :expense].include?(@parent.type)
+            raise ArgumentError, "Income/expense accounts can only be children of income/expense accounts"
+          end
+        else
+          unless @parent.type == @type
+            raise ArgumentError, "Account type #{@type} must match parent type #{@parent.type}"
+          end
+        end
+      end
+    end
+  end
+
+  # Custom error for account not found
+  class AccountNotFoundError < StandardError
+    def initialize(account_name)
+      super("Account '#{account_name}' not found. Please define it before referencing it in variables.")
+    end
+  end
+end
+

data/lib/fin_it/calculator/currency_conversion.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FinIt
+  class Calculator
+    # Currency conversion and exchange rate management
+    module CurrencyConversion
+      def configure_exchange_rates
+        # In production, fetch from API
+        # For now, use example rates
+        Money.add_rate('USD', 'MXN', 17.5)
+        Money.add_rate('MXN', 'USD', 0.057)
+        Money.add_rate('USD', 'EUR', 0.92)
+        Money.add_rate('EUR', 'USD', 1.09)
+        Money.add_rate('EUR', 'MXN', 18.9)
+        Money.add_rate('MXN', 'EUR', 0.053)
+      end
+      
+      def convert_currency(money, target_currency)
+        return money unless money.is_a?(Money)
+        return money if money.currency.iso_code == target_currency
+        
+        money.exchange_to(target_currency)
+      end
+    end
+  end
+end
+

data/lib/fin_it/calculator/date_helpers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FinIt
+  class Calculator
+    # Date parsing and period generation helpers
+    module DateHelpers
+      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
+        else
+          date
+        end
+      end
+
+      def generate_dates(start_date, end_date, frequency)
+        dates = []
+        current = start_date
+        
+        while current <= end_date
+          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
+    end
+  end
+end
+

data/lib/fin_it/calculator/variable_hashing.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module FinIt
+  class Calculator
+    # Handles variable hashing for cache invalidation
+    module VariableHashing
+      # Calculate hash for a variable (for cache invalidation)
+      def variable_hash(variable_name)
+        var_key = variable_name.is_a?(Symbol) ? variable_name : variable_name.to_sym
+        
+        # Check if it's a calculated variable
+        var_def = @variables[var_key]
+        if var_def.is_a?(Hash) && var_def[:type] == :calculated
+          return hash_calculated_variable(var_key, var_def)
+        end
+        
+        # Check if it's a temporal value (driver or financial variable)
+        temporal_value = @temporal_values[var_key]
+        if temporal_value
+          return hash_temporal_variable(temporal_value)
+        end
+        
+        # Fallback: hash the variable value itself
+        value = @variables[var_key]
+        hash_value(value)
+      end
+      
+      # Get all variable hashes
+      def all_variable_hashes
+        hashes = {}
+        
+        # Hash all variables
+        (@variables.keys + @temporal_values.keys).uniq.each do |var_name|
+          hashes[var_name] = variable_hash(var_name)
+        end
+        
+        hashes
+      end
+      
+      # Calculate hash for a complex model
+      def complex_model_hash(complex_model)
+        complex_model.hash(self)
+      end
+      
+      private
+      
+      def hash_calculated_variable(var_name, var_def)
+        # Hash = hash of dependencies + formula + dates + frequency + payment_schedule
+        deps = var_def[:dependencies] || extract_variable_dependencies(var_def[:formula])
+        dep_hashes = deps.map { |dep| variable_hash(dep) }.sort.join('|')
+        
+        hash_data = [
+          dep_hashes,
+          var_def[:formula],
+          var_def[:start_date]&.to_s,
+          var_def[:end_date]&.to_s,
+          var_def[:frequency]&.to_s,
+          var_def[:round_to]&.to_s,
+          hash_payment_schedule(var_def[:payment_schedule])
+        ].compact.join('|')
+        
+        Digest::SHA256.hexdigest(hash_data)
+      end
+      
+      def hash_temporal_variable(temporal_value)
+        # Hash = hash of all periods (values + dates + metadata)
+        periods = temporal_value.instance_variable_get(:@periods)
+        
+        period_data = periods.map do |period|
+          value_str = if period[:value].is_a?(Money)
+            "#{period[:value].fractional}:#{period[:value].currency.iso_code}"
+          else
+            period[:value].to_s
+          end
+          
+          [
+            value_str,
+            period[:start_date]&.to_s,
+            period[:end_date]&.to_s,
+            hash_metadata(period[:metadata])
+          ].compact.join('|')
+        end.join('||')
+        
+        Digest::SHA256.hexdigest(period_data)
+      end
+      
+      def hash_payment_schedule(schedule)
+        return '' unless schedule
+        
+        # Hash payment schedule if it's a PaymentSchedule object
+        if schedule.respond_to?(:frequency) && schedule.respond_to?(:payment_schedule)
+          [
+            schedule.frequency.to_s,
+            schedule.payment_schedule.to_s
+          ].join('|')
+        else
+          schedule.to_s
+        end
+      end
+      
+      def hash_metadata(metadata)
+        return '' unless metadata
+        
+        # Sort metadata keys for consistent hashing
+        metadata.sort_by { |k, _| k.to_s }.map { |k, v| "#{k}:#{v}" }.join(',')
+      end
+      
+      def hash_value(value)
+        if value.is_a?(Money)
+          Digest::SHA256.hexdigest("#{value.fractional}:#{value.currency.iso_code}")
+        else
+          Digest::SHA256.hexdigest(value.to_s)
+        end
+      end
+    end
+  end
+end
+