Fix IRR error when income > sum of payments

[sequba]

Context

The IRR function returns #NUM! error when the initial investment significantly exceeds the sum of returns (e.g., =IRR({-150000, 12000, 15000, 18000})). Excel correctly returns ~-41% for this case.

Root cause: The irrCore Newton-Raphson solver overshoots past the lower bound of -1 on the first iteration when the solution is a strongly negative rate. The code then unconditionally returns #NUM!.

Fix: Replace the unconditional error with a bisection-based clamp. When Newton-Raphson overshoots past -1, bisect between the current rate and -1: newRate = (rate - 1) / 2. This is guaranteed to stay in the valid domain (> -1) and converges linearly until close enough for quadratic Newton convergence to take over.

How did you test your changes?

Added 5 unit tests in the private tests repo covering:

• Bug reproduction: [-150000, 12000, 15000, 18000] with default guess
• Reversed cash flow signs: [150000, -12000, -15000, -18000]
• Highly negative IRR (near total loss): [-10000, 100, 100, 100]
• Negative IRR with explicit guess
• Large investment with many small returns

All 42 IRR tests pass (37 existing + 5 new), no regressions.

Types of changes

• Bug fix (a non-breaking change that fixes an issue)

Related issues:

1. Fixes [Bug]: IRR return error when income > sum of payments #1628

Checklist:

• I have reviewed the guidelines about Contributing to HyperFormula and I confirm that my code follows the code style of this project.
• I have signed the Contributor License Agreement.
• My change is compliant with the OpenDocument standard.
• My change is compatible with Microsoft Excel.
• My change is compatible with Google Sheets.
• I described my changes in the CHANGELOG.md file.
• My changes require a documentation update.
• My changes require a migration guide.

---

Note

Low Risk
Small, localized numerical-solver change plus non-runtime test/benchmark script updates; primary risk is altered IRR convergence behavior on edge-case inputs.

Overview
Fixes IRR returning #NUM! for strongly negative solutions by clamping Newton-Raphson iterations in irrCore when the next step overshoots past -1 (bisects back into the valid domain instead of immediately erroring).

Updates tooling/docs around the private test suite: renames the setup script to test:setup-private, adjusts fetch-tests.sh to create a missing branch from develop (and pull appropriately), and repoints benchmark scripts to test/hyperformula-tests/performance. Also records the IRR fix in CHANGELOG.md.

^{Written by Cursor Bugbot for commit 34b1265. This will update automatically on new commits. Configure here.}

[qunabu]

Task linked: HF-93 IRR returns error when income > sum of payments

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.18%. Comparing base (45ed5b8) to head (34b1265).
⚠️ Report is 15 commits behind head on develop.

Files with missing lines	Patch %	Lines
src/interpreter/plugin/FinancialPlugin.ts	80.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1627      +/-   ##
===========================================
- Coverage    97.18%   97.18%   -0.01%     
===========================================
  Files          172      172              
  Lines        14834    14836       +2     
  Branches      3257     3258       +1     
===========================================
+ Hits         14417    14418       +1     
- Misses         409      418       +9     
+ Partials         8        0       -8     

Files with missing lines	Coverage Δ
src/interpreter/plugin/FinancialPlugin.ts	99.45% <80.00%> (-0.28%)	⬇️

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.