Fix IRR error when income > sum of payments (#1627)

### 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
- [x] Bug fix (a non-breaking change that fixes an issue)

### Related issues:
1. Fixes #1628

### Checklist:
- [x] I have reviewed the guidelines about [Contributing to
HyperFormula](https://hyperformula.handsontable.com/guide/contributing.html)
and I confirm that my code follows the code style of this project.
- [ ] I have signed the [Contributor License
Agreement](https://goo.gl/forms/yuutGuN0RjsikVpM2).
- [x] My change is compliant with the
[OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html)
standard.
- [x] My change is compatible with Microsoft Excel.
- [x] My change is compatible with Google Sheets.
- [ ] I described my changes in the
[CHANGELOG.md](https://github.com/handsontable/hyperformula/blob/master/CHANGELOG.md)
file.
- [ ] My changes require a documentation update.
- [ ] My changes require a migration guide.


<!-- CURSOR_SUMMARY -->
---

> [!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`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
34b1265. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: sequba

CHANGELOG.md

@@ -7,6 +7,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed the IRR function returning `#NUM!` error when the initial investment significantly exceeds the sum of returns. [#1628](https://github.com/handsontable/hyperformula/issues/1628)
+
 ## [3.2.0] - 2026-02-19
 
 ### Added

package.json

@@ -76,10 +76,10 @@
     "verify:publish-package": "npm pack | node script/check-publish-package.js",
     "verify:typings": "tsc --noEmit",
     "test": "npm-run-all lint test:jest test:browser",
-    "test:fetch-private": "bash test/fetch-tests.sh",
+    "test:setup-private": "bash test/fetch-tests.sh",
     "test:jest": "cross-env NODE_ICU_DATA=node_modules/full-icu jest",
     "test:watch": "npm run test:jest -- --watch",
-    "test:tdd": "npm run test:jest -- --watch function-value",
+    "test:tmp": "npm run test:jest -- --watch function-irr",
     "test:coverage": "npm run test:jest -- --coverage",
     "test:logMemory": "npm run test:jest -- --runInBand --logHeapUsage",
     "test:performance": "npm run benchmark:basic && npm run benchmark:cruds",
@@ -88,10 +88,10 @@
     "test:browser": "cross-env-shell BABEL_ENV=dist env-cmd -f ht.config.js karma start",
     "test:browser.debug": "cross-env-shell BABEL_ENV=dist NODE_ENV=debug env-cmd -f ht.config.js karma start",
     "typedoc:build-api": "cross-env NODE_OPTIONS=--openssl-legacy-provider typedoc --options .typedoc.md.ts",
-    "benchmark:basic": "npm run tsnode test/performance/run-basic-benchmark.ts",
-    "benchmark:cruds": "npm run tsnode test/performance/run-cruds-benchmark.ts",
-    "benchmark:write-to-file": "npm run tsnode test/performance/write-to-file.ts",
-    "benchmark:compare-benchmarks": "npm run tsnode test/performance/compare-benchmarks.ts",
+    "benchmark:basic": "npm run tsnode test/hyperformula-tests/performance/run-basic-benchmark.ts",
+    "benchmark:cruds": "npm run tsnode test/hyperformula-tests/performance/run-cruds-benchmark.ts",
+    "benchmark:write-to-file": "npm run tsnode test/hyperformula-tests/performance/write-to-file.ts",
+    "benchmark:compare-benchmarks": "npm run tsnode test/hyperformula-tests/performance/compare-benchmarks.ts",
     "lint": "eslint . --ext .js,.ts",
     "lint:fix": "eslint . --ext .js,.ts --fix",
     "audit": "npm audit --omit=dev",

src/interpreter/plugin/FinancialPlugin.ts

@@ -876,19 +876,23 @@ function irrCore(values: number[], guess: number): number | CellError {
     }
 
     // Newton-Raphson step
-    const newRate = rate - npv / dnpv
+    let newRate = rate - npv / dnpv
+
+    if (!isFinite(newRate)) {
+      return new CellError(ErrorType.NUM)
+    }
+
+    // Clamp: when Newton overshoots past -1, bisect between current rate and -1
+    if (newRate <= -1) {
+      newRate = (rate - 1) / 2
+    }
 
     // Check for convergence based on rate change
     if (Math.abs(newRate - rate) < epsMax) {
       return newRate
     }
 
     rate = newRate
-
-    // Check for invalid rate
-    if (!isFinite(rate) || rate <= -1) {
-      return new CellError(ErrorType.NUM)
-    }
   }
 
   return new CellError(ErrorType.NUM)

test/README.md

@@ -12,7 +12,7 @@ The private test suite is kept in the `hyperformula-tests` repository. Once you
 
 Whenenever you switch branch in the main repository, you need to fetch the private test suite to the `test/hyperformula-tests` directory by running:
 ```
-npm run test:fetch-private
+npm run test:setup-private
 
 ```
 
@@ -45,7 +45,7 @@ This file is located in the `test` directory.
 3. **Checkout matching branch** – In `hyperformula-tests`:
    - Fetches from `origin`
    - Checks out the branch if it exists locally or on `origin`
-   - Otherwise checks out `develop`
+   - If the branch doesn't exist, creates it from `develop`
 
 4. **Pull latest** – Runs `git pull origin` on the checked-out branch.
 

test/fetch-tests.sh

@@ -28,16 +28,17 @@ fi
 
 echo "Checking out branch $CURRENT_BRANCH in hyperformula-tests..."
 
-# 3. Checkout matching branch in hyperformula-tests or fall back to develop
+# 3. Checkout matching branch in hyperformula-tests or create it if it doesn't exist
 cd "$HYPERFORMULA_TESTS_DIR"
 git fetch origin
 
 if git show-ref --verify --quiet "refs/heads/$CURRENT_BRANCH" || \
    git show-ref --verify --quiet "refs/remotes/origin/$CURRENT_BRANCH"; then
   git checkout "$CURRENT_BRANCH"
+  git pull # pull latest changes
 else
+  echo "Branch $CURRENT_BRANCH not found in hyperformula-tests, creating from develop..."
   git checkout develop
+  git pull origin develop
+  git checkout -b "$CURRENT_BRANCH"
 fi
-
-# 4. Pull changes from origin
-git pull origin "$(git rev-parse --abbrev-ref HEAD)"