HF-131 (4/7): expose which function produced an error, and which argument

[marcin-kordas-hoc]

What and why

Stacked on #1763. Exposes on the public DetailedCellError type the two fields the
origin/propagation mechanism (introduced in #1762) already computes internally:
originFunction?: string and argumentIndex?: number — which function or operator produced a
cell error, and, when it failed coercing one of its own arguments, which argument that was.

Revision note: an earlier version of this description said this PR built the mechanism
itself (the two choke points, Cell.ts's builders, etc.). That was wrong — the mechanism landed
in #1762 (see its revised description). This PR only does the public-facing exposure step the
mechanism commit's own message called out as a separate, later concern:

"originFunction and argumentIndex are carried on CellError and stamped in evaluateAst, but
DetailedCellError does not expose them yet... That split is the natural PR boundary here."

This PR is that boundary: expose the two fields, and wire the one direct caller outside the two
choke points.

What actually changes here (4 files, +32/-3):

• src/CellValue.ts — DetailedCellError gains originFunction/argumentIndex, copied from the
  underlying CellError in the constructor. Additive only: enumerable property count on
  DetailedCellError grows from 5 (type/message/value/address/hasMessage from HF-131 (3/7): a consumer can tell 'no message' from 'empty message' #1763) to 7.
• src/interpreter/plugin/FunctionPlugin.ts — coerceArgumentsToRequiredTypes's two error-return
  paths (wrong-type, non-scalar) now call .withArgumentIndex(i) — the only direct callers of
  that builder outside the two choke points HF-131 (2/7): the origin/propagation mechanism, plus the same guarantee outside the interpreter #1762 introduced.
• src/Cell.ts — withArgumentIndex's no-op gate also checks originFunction !== undefined, not
  just argumentIndex: needed so a nested call's own error (SQRT(-1) inside
  =DATE(1,1,SQRT(-1))) doesn't get DATE's argument index attached after already claiming its
  own origin.
• CHANGELOG.md — documents the two new public fields.

Verified against nested/propagated cases directly: =SUM(SQRT(-1)) reports SQRT, not SUM;
=1/0 then =SUM(A1) reports divide, propagated: true, not re-claimed by SUM;
=DATE(1,1,SQRT(-1)) reports {originFunction: 'SQRT', argumentIndex: undefined}, not a leaked
index on DATE's argument slot.

Known, deliberate limit: a binary operator's error names the operator (addWithEpsilon,
divide, etc.), not which operand failed — argumentIndex is only set for a function's own
coercion loop; the two operands of a binary op have no equivalent loop. Not solved here.

Verified

• npx tsc --noEmit — clean
• npx eslint src/ — 0 errors
• Full private test suite reproduced against this branch's tip — no regressions beyond the same
  pre-existing branch-pinning mismatch as the rest of this stack
• Zero surviving message-less CellError construction sites in src/ (carried over from HF-131 (2/7): the origin/propagation mechanism, plus the same guarantee outside the interpreter #1762;
  re-confirmed at this branch's tip)

Stack

4 of 7 — stacked on #1763. Next: fix/hf-131-rootless-origin.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes public error metadata and attribution rules during argument coercion; formula results should be unchanged but consumers and diagnostics depend on the new fields.

Overview
Exposes originFunction and argumentIndex on public DetailedCellError, copying them from the internal CellError so callers can see which function/operator produced an error and which formula argument failed coercion.

FunctionPlugin now tracks the user-written argument index through range expansion (listOfScalarValues / evaluateArguments add a 4th tuple field) and passes it into coerceArgumentsToRequiredTypes, which calls .withArgumentIndex(...) on wrong-type and non-scalar coercion failures so indices match the formula (e.g. a range counts as one argument, not N flattened cells).

Cell.withArgumentIndex is tightened so it is a no-op once originFunction is already set, preventing outer functions from attaching their argument slot to errors that nested calls already claimed (e.g. SQRT(-1) inside DATE(...)).

CHANGELOG documents the new fields and related error-metadata work in the HF-131 stack.

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

Performance

The hot-path change lives in #1762 and is measured there: total median −0.24% over three alternating
base/head rounds against origin/develop, within the run-to-run spread, with one CRUD benchmark
("Column ranges - add column") consistently about 3% slower. This PR adds fields to an object that
is only built when an error is exported, so it carries no measurable cost of its own.

[qunabu]

Task linked: HF-131 Verbose and actionable formula error messages

[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 1bb9db5. Configure here.}

[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	Updated (UTC)
❌ Deployment failed View logs	hyperformula-docs	efefce3	Sep 22 2026, 04:12 AM

[github-actions]

Performance comparison of head (efefce3) vs base (915ca17)

                                     testName |   base |    head | change
-------------------------------------------------------------------------
                                      Sheet A | 504.04 |  488.77 | -3.03%
                                      Sheet B | 164.09 |  157.19 | -4.21%
                                      Sheet T | 141.31 |  138.36 | -2.09%
                                Column ranges | 532.97 |  523.08 | -1.86%
                                Sorted lookup |  15510 | 15086.7 | -2.73%
Sheet A:  change value, add/remove row/column |  17.08 |   16.46 | -3.63%
 Sheet B: change value, add/remove row/column | 144.63 |  144.09 | -0.37%
                   Column ranges - add column | 166.16 |  161.23 | -2.97%
                Column ranges - without batch | 515.63 |  494.54 | -4.09%
                        Column ranges - batch | 128.63 |  126.57 | -1.60%

[Tobiadefami]

Could we preserve the original argument index through range expansion? With A1:A3 containing 1, =AND(A1:A3,"x") reports argumentIndex: 3, but "x" is the second argument, so the index should be 1. The .withArgumentIndex(i) calls in FunctionPlugin.ts:488–492 use the flattened position.

Carrying the original index alongside each expanded value fixed this for AND, OR, and XOR in a temporary patch. All 164 tests in the selected suites passed, along with TypeScript and lint.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.40%. Comparing base (915ca17) to head (efefce3).

Additional details and impacted files

@@                     Coverage Diff                     @@
##           feat/hf-131-has-message    #1764      +/-   ##
===========================================================
+ Coverage                    97.39%   97.40%   +0.01%     
===========================================================
  Files                          195      195              
  Lines                        15844    15848       +4     
  Branches                      3494     3497       +3     
===========================================================
+ Hits                         15431    15437       +6     
+ Misses                         405      403       -2     
  Partials                         8        8              

Files with missing lines	Coverage Δ
src/Cell.ts	95.31% <100.00%> (ø)
src/CellValue.ts	83.33% <100.00%> (+3.33%)	⬆️
src/interpreter/plugin/FunctionPlugin.ts	99.07% <100.00%> (+<0.01%)	⬆️

... and 1 file 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.