finrb 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5331d4b4769cc183d279c1eb4d837d05137cb6b09dd69394addb7be0c6debfae
-  data.tar.gz: de97a959862d55711e7e6989dc8c47ffa277dcea32cc8184cc89f2158edad160
+  metadata.gz: 8474be54c480d3150125ba2a00e7b935fbfb10281ce857304889ebca48839bac
+  data.tar.gz: 571f0f38b0a662c749df453e314cb3f916efe27e2f466896e600719a9048aef1
 SHA512:
-  metadata.gz: e57aeeac9a952790c895d367170596097d15fe5cbdb43bcab6a9943bfa80bff0a3a4d1e9d016e859d6f554b7a892a78ee2b3896f961b850f9ac1fafd7e064948
-  data.tar.gz: 84e26bbd5a9862c6733cbce98cebe4ebe1640751992c6fffe74d33ba31b39dc77f0f0ca5cf4ec8b6fd6bb6d0c62fa5bab1cbbacd3b0a8384d4d1eb1573b9528d
+  metadata.gz: 31edbc91ddfe6bfd433daaae2598be24b7fe22d604e40745b238a66c01ad8cd597d9a441b4643f9cd0a1adc5230cd2e3780fc1ba791e5799e921ffb0a6bc6e59
+  data.tar.gz: 59b760dfb7f1c27686d34362ad9da310b2bb20ccfc440b42f39e6c551fd14c1ac134dd3ed8795e0cf9d4274c264e085a95b59339bd71b5c11e6763f99f9b82a1

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # finrb changelog
 
+## 1.2.0
+
+### Validation and financial correctness
+
+- Apply the shared finite-decimal validation contract across yields, returns,
+  accounting, ratios, cashflows, rates, amortization, and TVM helpers.
+- Replace abbreviated validation errors with descriptive financial terms such
+  as period count, future value, face value, and compounding periods.
+- Add explicit denominator, rate, share-count, inventory, useful-life, and
+  residual-value domain checks while preserving valid decimal calculations and
+  return types.
+- Fix LIFO ending-inventory retention when a sale is satisfied by the second
+  purchase layer, preserving inventory cost conservation.
+- Reject invalid weighted-return vectors and replace the previous unsolicited
+  weighted-portfolio warning with an explicit validation error.
+
+### Development and project maintenance
+
+- Add deterministic `benchmark:run` scenarios using `benchmark-ips` for IRR,
+  XIRR, and amortization scaling, with known-root, equation-residual, solver
+  evaluation, and schedule-reconciliation preflight diagnostics.
+- Add contributor and security guidance, and link the project entry documents
+  from the README.
+- Include contributor and security documentation in packaged gem metadata.
+
 ## 1.1.0
 
 ### Investment returns and risk

data/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to finrb
+
+finrb welcomes focused bug fixes, documentation improvements, tests, and
+financial calculations that fit the project's scope. Before starting a large
+feature or public API change, open an issue so its financial conventions and
+design can be agreed upon first.
+
+## Development setup
+
+finrb requires Ruby 3.3 or newer. MRI 3.3, 3.4, and 4.0 are supported; JRuby
+and TruffleRuby are tested as informational compatibility targets.
+
+```shell
+bundle install
+bundle exec rake quality
+bundle exec rubocop
+```
+
+`rake quality` runs the RSpec suite with coverage, verifies maintained API
+examples, and validates the packaged RBS declarations. Additional checks are
+available for changes that affect their domains:
+
+```shell
+bundle exec rake security:audit
+bundle exec rake package:verify
+bundle exec rake benchmark:run
+bundle exec rake solver:verify
+```
+
+The solver verification task requires the optional Python environment
+documented in [spec/fixtures/README.md](spec/fixtures/README.md). The Python
+packages are development references and are not gem dependencies.
+
+## Making changes
+
+- Preserve unrelated code and behavior. Keep pull requests small enough to
+  review their financial and numerical consequences directly.
+- Follow the local Ruby style and run RuboCop. Comments should explain a
+  non-obvious reason or convention, not restate the code.
+- Route public numeric inputs through `Finrb::Validation`. Use `ArgumentError`
+  for malformed inputs and namespaced finrb errors for financial or numerical
+  domains.
+- Preserve `Flt::DecNum` calculations and return types unless the change has a
+  documented compatibility reason.
+- Update RBS declarations and user documentation when a public contract
+  changes.
+- Do not add an unreleased changelog section for ordinary development work.
+  The maintainer prepares the changelog as part of an actual release.
+
+## Numerical and financial changes
+
+A formula compiling or producing a plausible number is not sufficient
+verification. Describe the convention being implemented and test the relevant
+invariants, boundaries, and failure modes.
+
+For a solver or precision-sensitive change, include as appropriate:
+
+- known-root or algebraically constructed cases;
+- normalized equation residuals;
+- zero, negative-rate, long-horizon, and scale-sensitive cases;
+- attributable fixtures from a reputable independent implementation under
+  matching financial conventions;
+- deterministic seeds for generated cases; and
+- benchmarks that compare the same scenario across revisions, runtimes, or
+  architectures rather than ranking unrelated calculations.
+
+Reference fixtures must record their source, version, conventions, generation
+method, and tolerance. Do not replace committed fixtures merely to make a
+changed implementation pass without explaining why the reference changed.
+
+## Pull requests
+
+Use the pull request template and include:
+
+- the financial or technical problem;
+- the intended contract and compatibility impact;
+- the evidence used to verify correctness; and
+- any checks skipped because an optional runtime or external reference was
+  unavailable.
+
+Commit subjects in this repository commonly use the form
+`domain [Category]: Imperative summary`, for example:
+
+```text
+cashflows [Fix]: Preserve negative-root selection
+```
+
+By contributing, you agree that your work is provided under the repository's
+LGPL-3.0-or-later license.

data/README.md

@@ -64,8 +64,8 @@ API explicitly returns another financial object, such as `Finrb::Rate`.
 | `Finrb::Ratios` | Liquidity, leverage, profitability, and per-share ratios |
 | `Finrb::Accounting` | Inventory costing and depreciation |
 
-The detailed [API and examples guide](docs/api.md) lists each calculation and
-its parameters. Packaged RBS declarations are available under `sig/`.
+The [API and examples guide](docs/api.md) documents each financial domain and
+its public calculations. Packaged RBS declarations are available under `sig/`.
 
 ## Cashflows
 
@@ -338,6 +338,8 @@ Docker, batching, and tolerance details.
 - [RubyGems](https://rubygems.org/gems/finrb)
 - [Source](https://github.com/ncs1/finrb)
 - [Issue tracker](https://github.com/ncs1/finrb/issues)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
 
 ## Acknowledgements
 

data/SECURITY.md

@@ -0,0 +1,41 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made against the current released finrb line. Older
+versions may receive a fix when practical, but they are not guaranteed to be
+maintained. Users should reproduce an issue on the newest release before
+reporting it when possible.
+
+JRuby and TruffleRuby are informational compatibility targets. A
+runtime-specific vulnerability may also need to be reported to the relevant
+Ruby implementation or dependency maintainers.
+
+## Reporting a vulnerability
+
+Do not disclose a suspected vulnerability in a public issue, discussion, or
+pull request. Use GitHub's private vulnerability reporting for finrb:
+
+<https://github.com/ncs1/finrb/security/advisories/new>
+
+If private reporting is unavailable, contact the maintainer through the email
+listed in the gem metadata. Include only enough information in the initial
+message to establish a private channel.
+
+A useful report contains:
+
+- affected finrb and Ruby versions;
+- the affected API or packaged artifact;
+- minimal reproduction steps;
+- the expected and observed impact; and
+- any known mitigations or disclosure constraints.
+
+Please avoid including production credentials, private financial data, access
+tokens, or other secrets. There is no guaranteed response or remediation
+timeline; this project is maintained by one person. Reports will be evaluated
+according to reproducibility, impact, and available maintainer capacity.
+
+Numerical disagreement alone is normally a correctness bug rather than a
+security vulnerability. Treat it as security-sensitive when it can cross a
+trust boundary, bypass validation, enable denial of service, corrupt packaged
+artifacts, or predictably cause unsafe downstream financial decisions.

data/lib/finrb/accounting.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Inventory costing and depreciation calculations.
@@ -34,74 +35,32 @@ module Finrb
     # @example
     #   Finrb::Accounting.cogs(uinv=2,pinv=2,units=[3,5],price=[3,5],sinv=7,method="WAC")
     def self.cogs(uinv:, pinv:, units:, price:, sinv:, method: 'FIFO')
-      uinv = Flt::DecNum(uinv.to_s)
-      pinv = Flt::DecNum(pinv.to_s)
-      units = wrap_array(units).map { |value| Flt::DecNum(value.to_s) }
-      price = wrap_array(price).map { |value| Flt::DecNum(value.to_s) }
-      sinv = Flt::DecNum(sinv.to_s)
-      method = method.to_s
+      uinv, pinv, units, price, sinv, method = inventory_inputs(uinv:, pinv:, units:, price:, sinv:, method:)
 
       n = units.size
-      m = price.size
-      cost_of_goods = 0
-      ending_inventory = 0
-      if m == n
-        case method
-        when 'FIFO'
-          if sinv <= uinv
-            cost_of_goods = sinv * pinv
-            ending_inventory = (uinv - sinv) * pinv
-            (0...n).each do |i|
-              ending_inventory += (units[i] * price[i])
-            end
-          else
-            cost_of_goods = uinv * pinv
-            sinv -= uinv
-            (0...n).each do |i|
-              if sinv <= units[i]
-                cost_of_goods += (sinv * price[i])
-                ending_inventory = (units[i] - sinv) * price[i]
-                if i < n
-                  temp = i + 1
-                  (temp...n).each do |j|
-                    ending_inventory += (units[j] * price[j])
-                  end
-                end
-                sinv = 0
-                break
-              else
-                cost_of_goods += (units[i] * price[i])
-                sinv -= units[i]
-              end
-            end
-            raise(Error, "Inventory is not enough to sell\n") if sinv.positive?
-          end
-        when 'WAC'
-          ending_inventory = uinv * pinv
-          tu = uinv
+      cost_of_goods = Flt::DecNum(0)
+      ending_inventory = Flt::DecNum(0)
+      case method
+      when 'FIFO'
+        if sinv <= uinv
+          cost_of_goods = sinv * pinv
+          ending_inventory = (uinv - sinv) * pinv
           (0...n).each do |i|
             ending_inventory += (units[i] * price[i])
-            tu += units[i]
-          end
-          if tu >= sinv
-            cost_of_goods = ending_inventory / tu * sinv
-            ending_inventory = ending_inventory / tu * (tu - sinv)
-          else
-            raise(Error, "Inventory is not enough to sell\n")
           end
-
-        when 'LIFO'
-          (n - 1).downto(0).each do |i|
+        else
+          cost_of_goods = uinv * pinv
+          sinv -= uinv
+          (0...n).each do |i|
             if sinv <= units[i]
               cost_of_goods += (sinv * price[i])
               ending_inventory = (units[i] - sinv) * price[i]
-              if i > 1
-                temp = i - 1
-                temp.downto(0).each do |j|
+              if i < n
+                temp = i + 1
+                (temp...n).each do |j|
                   ending_inventory += (units[j] * price[j])
                 end
               end
-              ending_inventory += (uinv * pinv)
               sinv = 0
               break
             else
@@ -109,18 +68,52 @@ module Finrb
               sinv -= units[i]
             end
           end
-          if sinv.positive?
-            if sinv <= uinv
-              cost_of_goods += (sinv * pinv)
-              ending_inventory += ((uinv - sinv) * pinv)
-            else
-              raise(Error, "Inventory is not enough to sell\n")
+          raise(DomainError, 'Available inventory is insufficient for the requested sale.') if sinv.positive?
+        end
+      when 'WAC'
+        ending_inventory = uinv * pinv
+        tu = uinv
+        (0...n).each do |i|
+          ending_inventory += (units[i] * price[i])
+          tu += units[i]
+        end
+        if tu.zero? && sinv.zero?
+          cost_of_goods = Flt::DecNum(0)
+          ending_inventory = Flt::DecNum(0)
+        elsif tu >= sinv
+          cost_of_goods = ending_inventory / tu * sinv
+          ending_inventory = ending_inventory / tu * (tu - sinv)
+        else
+          raise(DomainError, 'Available inventory is insufficient for the requested sale.')
+        end
+
+      when 'LIFO'
+        (n - 1).downto(0).each do |i|
+          if sinv <= units[i]
+            cost_of_goods += (sinv * price[i])
+            ending_inventory = (units[i] - sinv) * price[i]
+            if i.positive?
+              temp = i - 1
+              temp.downto(0).each do |j|
+                ending_inventory += (units[j] * price[j])
+              end
             end
+            ending_inventory += (uinv * pinv)
+            sinv = 0
+            break
+          else
+            cost_of_goods += (units[i] * price[i])
+            sinv -= units[i]
+          end
+        end
+        if sinv.positive?
+          if sinv <= uinv
+            cost_of_goods += (sinv * pinv)
+            ending_inventory += ((uinv - sinv) * pinv)
+          else
+            raise(DomainError, 'Available inventory is insufficient for the requested sale.')
           end
         end
-
-      else
-        raise(Error, "length of units and price are not the same\n")
       end
 
       {
@@ -129,6 +122,20 @@ module Finrb
       }
     end
 
+    def self.inventory_inputs(uinv:, pinv:, units:, price:, sinv:, method:)
+      uinv = Validation.non_negative_decimal(uinv, name: 'beginning inventory units')
+      pinv = Validation.non_negative_decimal(pinv, name: 'beginning inventory unit cost')
+      units = inventory_values(units, name: 'purchase units')
+      price = inventory_values(price, name: 'purchase unit cost')
+      sinv = Validation.non_negative_decimal(sinv, name: 'units sold')
+      method = method.to_s
+      raise(ArgumentError, 'Inventory costing method must be FIFO, LIFO, or WAC.') unless %w[FIFO LIFO WAC].include?(method)
+      raise(ArgumentError, 'Purchase units and unit costs must have equal lengths.') unless units.size == price.size
+
+      [uinv, pinv, units, price, sinv, method]
+    end
+    private_class_method :inventory_inputs
+
     # Depreciation Expense Recognition -- double-declining balance (DDB), the most common declining balance method, which applies two times the straight-line rate to the declining balance.
     #
     # @param cost cost of long-lived assets
@@ -137,11 +144,10 @@ module Finrb
     # @example
     #   Finrb::Accounting.ddb(cost=1200,rv=200,t=5)
     def self.ddb(cost:, rv:, t:)
-      cost = Flt::DecNum(cost.to_s)
-      rv = Flt::DecNum(rv.to_s)
-      t = Flt::DecNum(t.to_s)
-
-      raise(Error, 't should be larger than 1') if t < 2
+      cost = Validation.non_negative_decimal(cost, name: 'asset cost')
+      rv = residual_value(rv, cost:)
+      t = Validation.positive_integer(t, name: 'useful life')
+      raise(DomainError, 'Useful life must be at least 2 periods for double-declining depreciation.') if t < 2
 
       ddb = [Flt::DecNum(0)] * t
       ddb[0] = cost * 2 / t
@@ -170,11 +176,24 @@ module Finrb
     # @example
     #   Finrb::Accounting.slde(cost=1200,rv=200,t=5)
     def self.slde(cost:, rv:, t:)
-      cost = Flt::DecNum(cost.to_s)
-      rv = Flt::DecNum(rv.to_s)
-      t = Flt::DecNum(t.to_s)
+      cost = Validation.non_negative_decimal(cost, name: 'asset cost')
+      rv = residual_value(rv, cost:)
+      t = Validation.positive_decimal(t, name: 'useful life', error: DomainError)
 
       ((cost - rv) / t)
     end
+
+    def self.inventory_values(values, name:)
+      wrap_array(values).map { |value| Validation.non_negative_decimal(value, name:) }
+    end
+    private_class_method :inventory_values
+
+    def self.residual_value(value, cost:)
+      value = Validation.non_negative_decimal(value, name: 'residual value')
+      raise(DomainError, 'Residual value must not exceed asset cost.') if value > cost
+
+      value
+    end
+    private_class_method :residual_value
   end
 end

data/lib/finrb/amortization.rb

@@ -37,7 +37,7 @@ module Finrb
         @interest_only = interest_only
         MONETARY_ATTRIBUTES.each do |name|
           value = binding.local_variable_get(name)
-          instance_variable_set("@#{name}", Validation.decimal(value, name: name.to_s))
+          instance_variable_set("@#{name}", Validation.decimal(value, name: name.to_s.tr('_', ' ')))
         end
         freeze
       end
@@ -91,16 +91,14 @@ module Finrb
     #   Amortization.payment(200000, rate.monthly, rate.duration) #=> Flt::DecNum('-926.23')
     # @see https://en.wikipedia.org/wiki/Amortization_calculator
     def self.payment(principal, rate, periods, balloon: 0)
-      principal = Validation.decimal(principal, name: 'principal')
-      raise(ArgumentError, 'principal must be positive.') unless principal.positive?
+      principal = Validation.positive_decimal(principal, name: 'principal', message: 'principal must be positive.')
 
       balloon = Validation.decimal(balloon, name: 'balloon')
       raise(ArgumentError, 'balloon must be non-negative and no greater than principal.') unless balloon.between?(0, principal)
 
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(ArgumentError, 'periodic rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'periodic rate')
 
-      periods = Validation.positive_integer(periods, name: 'periods')
+      periods = Validation.positive_integer(periods, name: 'period count')
 
       if rate.zero?
         # simplified formula to avoid division-by-zero when interest rate is zero
@@ -117,11 +115,9 @@ module Finrb
     # @param [Rate] rates the applicable interest rates
     # @param [Proc] block
     def initialize(principal, *rates, balloon: 0, interest_only_periods: 0, origination_fee: 0, finance_origination_fee: false, &block)
-      @principal = Validation.decimal(principal, name: 'principal')
-      raise(ArgumentError, 'principal must be positive.') unless @principal.positive?
+      @principal = Validation.positive_decimal(principal, name: 'principal', message: 'principal must be positive.')
 
-      @origination_fee = Validation.decimal(origination_fee, name: 'origination_fee')
-      raise(ArgumentError, 'origination_fee must be non-negative.') if @origination_fee.negative?
+      @origination_fee = Validation.non_negative_decimal(origination_fee, name: 'origination fee')
       raise(ArgumentError, 'finance_origination_fee must be true or false.') unless [true, false].include?(finance_origination_fee)
       raise(ArgumentError, 'an unfinanced origination_fee must be less than principal.') if !finance_origination_fee && @origination_fee >= @principal
 

data/lib/finrb/cashflows.rb

@@ -77,8 +77,7 @@ module Finrb
       validate_numeric_cashflows!
       cashflows = map { |entry| Validation.decimal(entry, name: 'cashflow amount') }
 
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(DomainError, 'Rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'rate', error: DomainError)
 
       total = Flt::DecNum.new(0.to_s)
       cashflows.each_with_index do |cashflow, index|
@@ -98,9 +97,8 @@ module Finrb
       cashflows = map { |entry| Validation.decimal(entry, name: 'cashflow amount') }
       raise(InvalidCashflowError, 'Cashflow needs at least one positive and one negative value.') if cashflows.none?(&:positive?) || cashflows.none?(&:negative?)
 
-      finance_rate = Validation.decimal(finance_rate, name: 'finance_rate')
-      reinvestment_rate = Validation.decimal(reinvestment_rate, name: 'reinvestment_rate')
-      raise(DomainError, 'Finance and reinvestment rates must be greater than -1.') if finance_rate <= -1 || reinvestment_rate <= -1
+      finance_rate = Validation.decimal_greater_than(finance_rate, minimum: -1, name: 'finance rate', error: DomainError)
+      reinvestment_rate = Validation.decimal_greater_than(reinvestment_rate, minimum: -1, name: 'reinvestment rate', error: DomainError)
 
       last_period = cashflows.size - 1
       future_positive =
@@ -156,8 +154,7 @@ module Finrb
     #   Finrb::Cashflow.xnpv(@transactions, 0.6).round(2) #=> -937.41
     def xnpv(rate)
       validate_dated_cashflows!
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(DomainError, 'Rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'rate', error: DomainError)
 
       sum do |t|
         t.amount / ((rate + 1)**(date_diff(start, t.date) / days_in_period))

data/lib/finrb/config.rb

@@ -41,16 +41,16 @@ module Finrb
   end
 
   def self.build_configuration(values)
-    eps = configuration_decimal(values.fetch(:eps), name: 'eps')
-    raise(ArgumentError, 'eps must be positive.') unless eps.positive?
+    eps = configuration_decimal(values.fetch(:eps), name: 'solver tolerance')
+    raise(ArgumentError, 'solver tolerance must be positive.') unless eps.positive?
 
-    guess = configuration_decimal(values.fetch(:guess), name: 'guess')
-    raise(ArgumentError, 'guess must be greater than -1.') if guess <= -1
+    guess = configuration_decimal(values.fetch(:guess), name: 'rate guess')
+    raise(ArgumentError, 'rate guess must be greater than -1.') if guess <= -1
 
     business_days = values.fetch(:business_days)
     periodic_compound = values.fetch(:periodic_compound)
     booleans = [business_days, periodic_compound].all? { |value| value.equal?(true) || value.equal?(false) }
-    raise(ArgumentError, 'business_days and periodic_compound must be boolean.') unless booleans
+    raise(ArgumentError, 'business days and periodic compounding settings must be boolean.') unless booleans
 
     Configuration.new(eps:, guess:, business_days:, periodic_compound:)
   end

data/lib/finrb/rates.rb

@@ -17,10 +17,7 @@ module Finrb
       infinite = value.infinite? if value.respond_to?(:infinite?)
       return Flt::DecNum.infinity if [true, 1].include?(infinite)
 
-      periods = Validation.decimal(value, name: 'compounding periods')
-      raise(ArgumentError, 'compounding periods must be positive.') unless periods.positive?
-
-      periods
+      Validation.positive_decimal(value, name: 'compounding periods', message: 'compounding periods must be positive.')
     end
     private_class_method :compounding_periods
 
@@ -49,8 +46,7 @@ module Finrb
     #   Rate.to_nominal(0.06, 365) #=> Flt::DecNum('0.05827')
     # @see https://www.miniwebtool.com/nominal-interest-rate-calculator/
     def self.to_nominal(rate, periods)
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(ArgumentError, 'effective rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'effective rate')
 
       periods = compounding_periods(periods)
 
@@ -141,7 +137,7 @@ module Finrb
     end
 
     def duration=(value)
-      @duration = Validation.positive_integer(value, name: 'duration')
+      @duration = Validation.positive_integer(value, name: 'duration in months')
     end
 
     # set the effective interest rate