feat(config): add arrayFunctionResultOverwritesData opt-in overwrite flag (HF-305)

[marcin-kordas-hoc]

Implements HF-305. Paired tests: hyperformula-tests#45 (branch feat/hf-305-overwrite-flag, same name — merge it first).

What & why

Adds an opt-in boolean config option arrayFunctionResultOverwritesData (default false).

• false (default): unchanged behavior — an array function spilling onto an occupied cell yields #SPILL! and leaves the occupant intact.
• true: the spill overwrites the occupied cells (clears occupants, spills the array, reroutes dependents) instead of emitting #SPILL!.

Requested by a customer; the feature + option name were pre-agreed (~8 SP).

How

Reuses the existing spill-placement exchange primitive rather than inventing a mechanism:

• ConfigParams / Config: new option, mirrored on useArrayArithmetic.
• DependencyGraph gains config + two guarded early-returns (exchangeOrAddFormulaVertex, setAddressMappingForArrayVertex).
• Evaluator: recompute no longer emits #SPILL! when overwrite is allowed.

Array-vs-array safety: a spill colliding with another array always keeps #SPILL! and leaves that array intact, even in overwrite mode (canOverwriteArrayResult / overwriteWouldHitArray). Matches Excel; overwrite only clears static data. Default false guarantees no silent data loss.

Tests

They live in hyperformula-tests#45, unit/array-function-result-overwrites-data.spec.ts — 53 cases in nine groups: configuration parsing · disabled (default) parity · enabled overwrite incl. dependent reroute and 2-D blocks · array-vs-array collisions keeping #SPILL! · undo and redo · column-index staleness (incl. addColumns growth) · structural operations · cycles · unrepresentable spill ranges.

They arrived on this branch as test/hf-305-overwrite.spec.ts, in the public repository. Specs do not live here — #1612 took every test out of handsontable/hyperformula, which is why test/ on develop carries only the setup files, fetch-tests.sh and smoke.spec.ts. Jest's testMatch did pick the file up, so the suite was running; it was running from the wrong repository. Moved in f051ab3.

Verification of the move:

• 53/53 green under Jest against this branch.
• Patch coverage closed. Every executable line this PR adds to src/Operations.ts (29) and src/DependencyGraph/DependencyGraph.ts (17) is exercised by that spec alone — measured by intersecting this PR's added lines with a coverage run of the single file. That is what the red codecov/patch was reporting.
• Not vacuous — four mutations, all killed: canOverwriteArrayResult forced to false → 22 failures; the snapshot guard flipped (<= 1 → >= 1) → 6; the EmptyCellVertex guard on the overwrite content-change inverted → 3; the array-vs-array guard removed → 3.

Known limitations

The opt-in overwrite behavior is intentionally scoped to the direct spill/recalc path. The following edges are not fully handled yet; each is a nuance to weigh, not a silent-corruption risk (the default false config is fully backward compatible and untouched by all of these):

• buildFromArray initial-build path: declaring an array formula and a conflicting occupant in the same initial buildFromArray call still lets the occupant win — overwrite only applies on the recalc / setCellContents path (existing data, then an array formula lands on it), not the un-gated initial-build placement path.
• Undo does not restore cells overwritten via direct setCellContents — no longer true, and this line was stale. setCellContent now returns { oldContent, overwrittenCells } from a pre-spill snapshot, and SetCellContentsUndoEntry restores them after the anchor formula is reverted. Pinned by eight undo/redo cases (value, formula, multiple occupants, rerouted dependent, redo, expand-over-static, blocked array-vs-array).
• The undo leg of the structural-op path is still unpinned. When addColumns/addRows/removeColumns/removeRows shifts a dependency so an existing array grows over a previously-static cell, the overwrite itself is handled correctly for evaluation and for useColumnIndex (the stale value is dropped from the index at the moment of overwrite — see rewriteAffectedArrays), and both are pinned by tests. What no test covers either way is whether undoing that structural op restores the static cell. Measured for the direct-edit expand path — it does restore — but the structural path was not reproduced. This is the item for the reviewer to weigh, and it is narrower than the version this section previously described.
• useColumnIndex + undo, on the structural path only: a workflow relying on undo() to roll back an overwrite that a structural op caused may see the array formula disappear while the previously-static data stays gone; the index and the data would then be consistent with each other but not with the pre-overwrite state. On the direct-edit path this no longer applies — undo restores both the cell and its index entry, and that is pinned.

None of these limitations can produce the crash or stale-lookup-index bugs originally flagged by Bugbot on this PR — both were reproduced with throwaway probes and fixed at the root cause (see review thread replies on commit b877ed4). What remains out of scope is exclusively the undo leg of overwrite bookkeeping.

---

Note

Medium Risk
Opt-in destructive sheet mutation in dependency graph and CRUD/undo paths; default false preserves Excel-compatible behavior, but enabled mode can clear live cell data and depends on correct column-index and undo bookkeeping.

Overview
Adds arrayFunctionResultOverwritesData (default false). When enabled, array formulas that would spill onto occupied non-array cells clear those cells and place the spill instead of returning #SPILL!. Collisions with another array or an unrepresentable spill range still yield #SPILL!; initial buildFromArray placement is unchanged (occupant wins).

Dependency graph: DependencyGraph now holds config and uses canOverwriteArrayResult / overwriteWouldHitArray so exchangeOrAddFormulaVertex can claim occupied spill cells, record content changes for the column index, and only then evaluate. The graph build path (setAddressMappingForArrayVertex) does not use overwrite mode.

CRUD & undo: setCellContent returns { oldContent, overwrittenCells } with a pre-spill snapshot of cleared occupants; SetCellContentsUndoEntry restores them after reverting the anchor formula. restoreCell / rewriteAffectedArrays apply column-index updates so stale lookup values are not left after overwrite or undo on the direct-edit path.

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

[qunabu]

Task linked: HF-305 Array functions overwrite data instead of SPILL

[netlify]

✅ Deploy Preview for hyperformula-dev-docs ready!

Name	Link
🔨 Latest commit	467c186
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a6602deeedd020008331aa9
😎 Deploy Preview	https://deploy-preview-1714--hyperformula-dev-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

Performance comparison of head (e410ed0) vs base (114fd5d)

                                     testName |    base |    head | change
--------------------------------------------------------------------------
                                      Sheet A |   315.8 |  304.38 | -3.62%
                                      Sheet B |   99.44 |   98.39 | -1.06%
                                      Sheet T |   88.98 |   86.61 | -2.66%
                                Column ranges |   461.2 |  455.76 | -1.18%
                                Sorted lookup | 15566.6 | 16955.9 | +8.92%
Sheet A:  change value, add/remove row/column |    9.68 |    8.88 | -8.26%
 Sheet B: change value, add/remove row/column |   87.82 |    82.9 | -5.60%
                   Column ranges - add column |   108.3 |  109.81 | +1.39%
                Column ranges - without batch |  343.89 |  350.97 | +2.06%
                        Column ranges - batch |   89.55 |   91.17 | +1.81%

[marcin-kordas-hoc]

bugbot run

[marcin-kordas-hoc]

bugbot run

[marcin-kordas-hoc]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 5e397d1. Configure here.}

[marcin-kordas-hoc]

bugbot run

[marcin-kordas-hoc]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 467c186. 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	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	e410ed0	Commit Preview URL Branch Preview URL	Aug 31 2026, 07:37 AM

[marcin-kordas-hoc]

Known-gap disclosure from writing the paired suite (tests #45), re-verified today on this head (3e2a099): with the flag ON, an array whose spill range cannot be represented silently loses #SPILL! and truncates to its anchor.

Repro: useArrayArithmetic: true, =2*(B:B) in A2 — flag OFF: #SPILL! (pinned by arrays.spec.ts); flag ON: A2 = 2, no error indicator anywhere. Same silent truncation on the buildFromArray / updateConfig path.

Root cause: overwriteWouldHitArray returns false for an undefined range, so canOverwriteArrayResult returns true and Evaluator skips setNoSpace(). Overwrite mode should bypass occupancy collisions only, not a range that cannot be spanned at all — suggested one-line fix: canOverwriteArrayResult returns false when arrayVertex.getRangeOrUndef() is undefined.

The paired suite deliberately pins only the stable half (occupants below are not clobbered), so it stays green whichever way this is resolved.

[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.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 08f5a06. Configure here.}

[marcin-kordas-hoc]

Fixed in e410ed0f2 (tests 1116587, +4 cases → 60). The operative insight: every legitimate overwrite claims its spill range in the address mapping (exchangeOrAddFormulaVertex) before evaluation, so isThereSpaceForArray is already true when the array recomputes — the canOverwriteArrayResult bypass in Evaluator could only ever fire for arrays whose overwrite never happened, which is exactly the two silent-truncation paths. The bypass is removed; canOverwriteArrayResult additionally refuses an unrepresentable range as a defensive guard, and the build path keeps #SPILL! under the flag exactly as with it off. Fail-then-pass: the 3 new error assertions fail on the previous head, 60/60 after; changelog clause added. Verified independently on the pushed head: =2*(B:B) and the build-time collision both show #SPILL! with the flag on.

[codecov]

Codecov Report

❌ Patch coverage is 96.72131% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.34%. Comparing base (114fd5d) to head (e410ed0).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
src/DependencyGraph/DependencyGraph.ts	90.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1714      +/-   ##
===========================================
+ Coverage    97.32%   97.34%   +0.01%     
===========================================
  Files          195      195              
  Lines        15739    15790      +51     
  Branches      3390     3402      +12     
===========================================
+ Hits         15318    15370      +52     
+ Misses         421      420       -1     

Files with missing lines	Coverage Δ
src/Config.ts	94.17% <100.00%> (+0.05%)	⬆️
src/CrudOperations.ts	99.20% <100.00%> (+<0.01%)	⬆️
src/Evaluator.ts	100.00% <ø> (ø)
src/Operations.ts	98.98% <100.00%> (+0.04%)	⬆️
src/UndoRedo.ts	100.00% <100.00%> (ø)
src/DependencyGraph/DependencyGraph.ts	98.58% <90.00%> (-0.23%)	⬇️

... 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.