Add FORECAST.LINEAR, INTERCEPT, TREND, GROWTH and LOGEST functions

[Tobiadefami]

Context

This PR adds five regression functions: FORECAST.LINEAR (also available under its legacy name FORECAST),
INTERCEPT, TREND, GROWTH and LOGEST.

Important

Stacked on #1769 (LINEST). TREND, GROWTH and LOGEST reuse LINEST's least-squares fit and its input
helpers, so this branch is based on feature/hf-221-linest. Until #1769 merges, this diff also shows LINEST's
commits. Review only the commits from feat(HF-414): add INTERCEPT and FORECAST.LINEAR onward:
feat(HF-414): add INTERCEPT and FORECAST.LINEAR, feat(HF-414): add TREND, GROWTH and LOGEST,
docs(HF-414): link the pull request in the changelog, fix(HF-414): accept the text TRUE and FALSE as const and stats
and feat(HF-414): list the regression functions in the license catalog. Once #1769 merges, this branch will be
rebased onto develop and only these commits will remain.

Behavior, checked against Excel:

• FORECAST.LINEAR and INTERCEPT pair known_y/known_x like SLOPE: a pair is skipped when either value is
  blank, text, numeric text or a boolean, and an error in a pair is returned. Ranges need the same number of cells
  (#N/A otherwise); fewer than two pairs, or x values that are all equal, return #DIV/0!.
• TREND, GROWTH and LOGEST follow LINEST: every known value must be a number (#VALUE! otherwise), dimensions
  must be compatible (#REF!), and several x-variables are supported in column or row orientation. known_x
  omitted means 1, 2, 3, …; new_x omitted means known_x.
• Collinear x-columns are handled as in LINEST: the later column is kept and the removed one gets a coefficient of
  0 (LOGEST shows its base as 1).
• GROWTH and LOGEST require positive known_y values (#NUM! otherwise). GROWTH evaluates b·m^x as Excel
  does, so overflow and underflow give #NUM! in the affected cells.
• LOGEST returns LINEST's layout: one row of bases and the constant, or five rows with stats set. The
  statistics are LINEST's statistics of the fit to ln y.
• const and stats: a blank cell is FALSE, an empty argument is the default, numbers and booleans are coerced, the
  text "TRUE" or "FALSE" (in any letter case) is accepted as in LINEST, and other text is #VALUE!. An error written in the formula is returned as is; a cell holding an error gives #VALUE!, as in
  Excel.

Note: Microsoft's FORECAST.LINEAR and INTERCEPT pages say empty data returns #N/A. Excel returns #DIV/0!, and
this implementation follows Excel.

Implementation

• INTERCEPT and FORECAST.LINEAR live in StatisticalAggregationPlugin, next to SLOPE, and reuse its pairing
  helper. A new private simpleLinearFit computes the line with plain two-pass sums, which reproduces Excel's last
  digits more closely than the jStat helpers SLOPE uses. SLOPE is unchanged. FORECAST is an alias of
  FORECAST.LINEAR.
• TREND, GROWTH and LOGEST live in RegressionPlugin, next to LINEST, and reuse regressionShape,
  buildPredictorRows, regressionOutput and fitLinearRegression. LINEST's existing code is not modified.
• TREND and GROWTH share one method and a new size method, trendArraySize, which predicts the result size from
  new_x (or known_y when new_x is omitted). LOGEST shares LINEST's size method, linestArraySize, because
  both return the same coefficient and statistics layout.
• New error messages: ZeroVariance, PositiveValues, and the parameterized StaticResultSize(name) and
  StaticStats(name). No new error types.
• Catalogue entries in categories/statistical.ts, and names in all language packs, read from Excel in each
  locale. FORECAST.LINEAR is not localized in any Excel locale; FORECAST is.
• License catalog: the five functions are listed among the ungrouped functions in functionCapabilities.ts, so
  fun:all and their single-function tokens cover them. FORECAST travels with FORECAST.LINEAR as an alias.
• Docs: a TREND, GROWTH and LOGEST section in list-of-differences.md and in known-limitations.md, next to
  LINEST's.

How did you test your changes?

• Expected values come from Microsoft Excel Online (en-US). Each test is one measured case, entered on the same
  data the tests use, so any case can be re-checked in Excel.
• 566 new tests in hyperformula-tests: function-forecast.linear 97, function-intercept 70, function-trend
  138, function-growth 136, function-logest 125. Numbers are compared with a relative tolerance, as in
  function-linest.spec.ts, because the fit can differ from Excel in the last digits. Cases cover the docs examples,
  exact and noisy data, several variables in both orientations, collinear columns, const and stats, coercion and
  errors in every argument, error precedence, and the FORECAST alias.
• Full Jest suite with the private tests on this branch: 506 of 508 suites pass (6,916 tests passed, 3 skipped,
  pre-existing). The 7 failures are all VERSION tests in function-version.spec.ts and function-metadata-api.spec.ts:
  HF-307: license-key entitlement gating — capability model, key reader, API guards #1728 changed VERSION, and the tests branch is based on LINEST's tests branch, which does not include develop's
  updated specs yet. With develop's versions of those two specs, both pass. function-linest.spec.ts passes
  unchanged.
• License catalog: develop's capability-registry.spec.ts completeness check covers all five functions (the only name it
  reports is LINEST, which is handled in feat(HF-221): add LINEST regression function #1769).
• Mutation check: breaking one rule per function fails tests.
• npm run lint (no new warnings), npm run compile, npm run docs:generate-function-docs, git diff --check.

Types of changes

• Breaking change (a fix or a feature because of which an existing functionality doesn't work as expected anymore)
• New feature or improvement (a non-breaking change that adds functionality)
• Bug fix (a non-breaking change that fixes an issue)
• Additional language file, or a change to an existing language file (translations)
• Change to the documentation

Related issues:

1. Depends on feat(HF-221): add LINEST regression function #1769 (LINEST).
2. Tests: handsontable/hyperformula-tests#76

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.

🤖 Generated with Claude Code

---

Note

Medium Risk
Large new numerical and array-sizing paths affect formula evaluation and spilled results; behavior is Excel-sensitive but confined to statistical functions rather than core engine security.

Overview
Adds Excel-style linear and exponential regression to the formula engine: LINEST (simple/multiple regression with optional statistics), plus FORECAST.LINEAR / FORECAST, INTERCEPT, TREND, GROWTH, and LOGEST.

INTERCEPT and FORECAST.LINEAR are implemented in StatisticalAggregationPlugin via a new simpleLinearFit helper (pairing behavior aligned with SLOPE). LINEST, TREND, GROWTH, and LOGEST live in a new RegressionPlugin backed by fitLinearRegression (Householder QR) in LinearRegression.ts, with shared shape/prediction helpers and static array-size prediction so stats (and result width for LINEST/LOGEST) must be constants—mismatches yield #VALUE!.

Also adds regression-specific error messages, statistical function metadata, localized names across language packs, changelog entries, and docs on limitations and Excel differences (constant stats, pre-sized arrays, numerical edge cases). The unreleased changelog in this diff also records unrelated fixes (MOD, pool functions, etc.) if they ship in the same release.

^{Reviewed by Cursor Bugbot for commit 2bad285. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cla-external-contractor-signup]

@Tobiadefami thanks for the pull request. No CLA step needed here — our records show you signed the Contributor License Agreement on 2026-07-31. That signature came from our previous signing form and has been carried over, so there is nothing for you to re-sign.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	130c9dc	Commit Preview URL Branch Preview URL	Oct 08 2026, 10:55 PM

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

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

^{Reviewed by Cursor Bugbot for commit 130c9dc. Configure here.}

[cursor]

LINEST omitted from license table

Medium Severity

LINEST is a new built-in in RegressionPlugin but is not listed in UNGROUPED_FUNCTIONS or any FUNCTION_GROUPS entry. A built-in absent from this table is not gated, so a subset license that does not include LINEST still evaluates it. FORECAST.LINEAR, INTERCEPT, TREND, GROWTH, and LOGEST were added to the same list.

 

^{Reviewed by Cursor Bugbot for commit 130c9dc. Configure here.}

[github-actions]

Performance comparison of head (130c9dc) vs base (eff7928)

                                     testName |    base |    head |  change
---------------------------------------------------------------------------
                                      Sheet A |  389.26 |  399.01 |  +2.50%
                                      Sheet B |  126.03 |  133.63 |  +6.03%
                                      Sheet T |  110.44 |   115.4 |  +4.49%
                                Column ranges |  416.47 |  423.77 |  +1.75%
                                Sorted lookup | 12401.4 | 12555.4 |  +1.24%
Sheet A:  change value, add/remove row/column |   12.87 |   15.01 | +16.63%
 Sheet B: change value, add/remove row/column |  115.92 |  135.06 | +16.51%
                   Column ranges - add column |  129.12 |  142.23 | +10.15%
                Column ranges - without batch |  423.25 |  425.45 |  +0.52%
                        Column ranges - batch |  108.49 |   102.1 |  -5.89%