HF-307: align getRegisteredFunctionNames with the license gate, deprecate its static form

[marcin-kordas-hoc]

Update 2026-09-18 — rebased onto the collapsed engine/tests PRs

hyperformula#1730 and hyperformula-tests#32 were folded from five PRs each into one, so this
PR's base moved to #1730. Nothing in this PR's own diff changed; the "9/9" numbering and the
#1741 base reference below are stale — the stack is now #1728 → #1729 → #1730 → this PR.

---

9/9 of the HF-307 stack, stacked on #1741. Pairs with hyperformula-tests#43 — merge the tests PR first. Finishes decision D2 on the one API it missed.

The problem

getRegisteredFunctionNames() returned the whole catalogue under a restricted key (measured: 422 names on a calculated-fields key, including functions that evaluate to #LIC!). A function picker built on it has exactly the problem #1724 (HF-349) and #1731's metadata filter exist to prevent. Flagged in #1731's "found, not fixed here" section; this closes it.

What changed

Instance method — now lists exactly what the instance can evaluate, sharing the one licenseListsFunction rule with the interpreter and the metadata API so the three surfaces cannot drift:

• reads getListableFunctionIds() instead of getRegisteredFunctionIds() — the protected built-ins are included uniformly (OFFSET was missing before; getAvailableFunctions already listed it);
• reads config.translationPackage — the instance's own snapshot — instead of a fresh global getLanguage lookup, which can report a localized name the instance refuses to evaluate, and which throws once the host unregisters that language code;
• filters by the license, with the invariant intact: a missing, invalid, or expired key does not shorten the list.

Static method — deprecated, not removed. See below; this is a change from the first version of this PR.

The static: deprecated rather than removed (changed after review)

The first version of this PR deleted HyperFormula.getRegisteredFunctionNames(code), citing HF-349 as precedent. That was wrong, and the review caught it:

$ git show 3.4.0:src/HyperFormula.ts | grep -c "public static getRegisteredFunctionNames"   # 1

The method is in the released 3.4.0 tag, and HF-349's own commit message says its removal was free precisely because "Both methods are unreleased, which is the only free moment to remove them." So the precedent does not extend here: deleting it would be a breaking change in a minor release, against the Semantic Versioning this project states it follows, and DEV_DOCS's Definition of Done would require a migration-guide section that docs/guide/ has no 3.x home for.

So it is now @deprecated with the wording this repo already uses for that situation (arraySizeMethod / arrayFunction in 3.1.0: "deprecated and will be removed in one of the next major releases"), plus a Deprecated changelog entry. Overturnable in one comment if you would rather take the break now — the direction is Kuba's D2 either way; only the timing changed.

The deprecation notice is explicit that the two are not interchangeable: the static translates into any registered language without an engine, so migrating means building one (HyperFormula.buildEmpty({ language: 'plPL' }).getRegisteredFunctionNames()).

D2's precondition, discharged

Kuba's D2 answer made the removal conditional: "perhaps we can remove the static methods, I'll check which methods does formula-builder use". That check is done — searched the org, and both consumers call the instance form, not the static one:

Consumer	Call site	Form
formula-builder	packages/core/src/engine/functionCatalog.ts:81 — this.engine?.getRegisteredFunctionNames?.(), in try/catch, declared optional in engine/types.ts:66	instance
aurasheet	src/core/FormulaEngine.ts:97 — this.hf.getRegisteredFunctionNames()	instance

Both use it to build a function picker (functionCatalog.ts; FormulaAutocompletePlugin.ts) — the surface #1724's rationale was about — so the license filter added here improves both rather than disturbing them. Under gpl-v3 or any unrestricted key their lists are unchanged.

Spec-to-ship review (2026-08-20): also fixed here

• The translation-snapshot change was unpinned. Mutation-verified: reverting it to the global lookup left 309 tests green, even though the commit message and the new JSDoc both name it. Now pinned by a test that unregisters the language after the engine is built — the scenario that distinguishes the two implementations, since getLanguage throws for an unregistered code while the snapshot keeps working.
• The licence guide listed only two of the three narrowing methods. It now names this one too, in both places.
• The new JSDoc over-claimed parity with getAvailableFunctions: for a function whose translation is the empty string this method returns '' while that one falls back to the canonical id. The claim is now scoped to the ids and the licence rule, with the naming difference stated.
• Reverting the static removal also removed the docs-build change it required, so docs/.vuepress/config.js is untouched by this PR again (it no longer builds one engine per documentation page).

Testing

New suite pins the alignment in both directions (agrees with getAvailableFunctions name for name; narrows on a restricted key; never narrows on a bad key; aliases gate with their canonical; answers from the instance's own snapshot). Full private suite: 517 suites / 6462 passing, 3 pre-existing skips; tsc --noEmit and ESLint clean.

Note for review

functions-metadata.spec.ts now skips listed ids with no plugin: OFFSET is listed (it is callable) but parse-time resolved, so it legitimately has no registry metadata.

🤖 Generated with Claude Code

https://claude.ai/code/session_019pxNP45obT2LZfjitaCv9o

The codecov/project dip, traced

codecov/project was red at −0.02% while codecov/patch reported 100% of the diff hit. Rather than
write that off as a threshold artifact, I measured coverage on this commit and on its base and
diffed the per-file numbers:

file	base (8/9)	this PR, before the fix
src/HyperFormula.ts	674 / 675	675 / 676
src/interpreter/FunctionRegistry.ts	130 / 130	129 / 130
total	12 933 / 13 268	12 933 / 13 269

So the covered count did not move and one previously covered line stopped executing — a real
consequence of this change, not a rounding artifact. The line was the instance
FunctionRegistry.prototype.getRegisteredFunctionIds(), whose only caller in the whole repository
was the method this PR rewrites. Nothing in src/, nothing in the private suite, and nothing
outside (the class is not exported from src/index.ts) calls it any more.

Removed, since this change is what orphaned it. The static FunctionRegistry.getRegisteredFunctionIds()
is untouched and still used — by the deprecated static method above and by three specs.

For the record, the single uncovered line left in HyperFormula.ts is pre-existing and not mine:
removeNamedExpression's unreachable return [], which already carries a codecov note comment
explaining why it cannot be hit.

---

Note

Medium Risk
Changes public API behavior for function pickers under restricted keys and deprecates a shipped static method; evaluation logic is unchanged but listing surfaces must stay consistent with licensing.

Overview
Instance getRegisteredFunctionNames() now lists only functions the engine can evaluate under the current license—the same rule as getAvailableFunctions() / getFunctionDetails(). It uses listable ids (protected built-ins like OFFSET included), filters with licenseListsFunction, and reads names from the instance translationPackage snapshot instead of a global language lookup. Missing, invalid, or expired keys still do not shorten the list.

The static HyperFormula.getRegisteredFunctionNames(language) is deprecated (kept for semver because it shipped in 3.4.0), with docs and changelog pointing callers at the instance API—e.g. HyperFormula.buildEmpty({ language: 'plPL' }).getRegisteredFunctionNames().

Internal cleanup: instance FunctionRegistry.getRegisteredFunctionIds() is removed as unused. License docs and changelog document the third narrowed listing API and the deprecation; changelog also adds a retroactive 3.4.0 note that static metadata helpers were removed.

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

[qunabu]

Task linked: HF-307 Implement feature packages and add-ons in HF
Task linked: HF-349 Static methods cannot read functions granted by license key

[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	fab1a6f	Sep 22 2026, 01:40 PM

[github-actions]

Performance comparison of head (fab1a6f) vs base (f782d0e)

                                     testName |    base |   head | change
-------------------------------------------------------------------------
                                      Sheet A |  488.37 | 500.77 | +2.54%
                                      Sheet B |  153.05 | 159.74 | +4.37%
                                      Sheet T |  137.19 | 145.93 | +6.37%
                                Column ranges |  468.58 | 482.01 | +2.87%
                                Sorted lookup | 14411.9 |  15006 | +4.12%
Sheet A:  change value, add/remove row/column |   14.77 |  16.18 | +9.55%
 Sheet B: change value, add/remove row/column |  128.26 | 139.69 | +8.91%
                   Column ranges - add column |  148.86 | 161.48 | +8.48%
                Column ranges - without batch |  476.64 | 495.01 | +3.85%
                        Column ranges - batch |  116.32 | 121.43 | +4.39%

[Tobiadefami]

Reviewed at dcf9354 together with the paired tests at a406fc76. I checked the instance registry and translation snapshots, license filtering, aliases, custom and protected functions, raw translation behavior, static API compatibility and deprecation, documentation, changelog, and current automated findings. The focused paired run passes 17 suites (317 tests), TypeScript passes, and all current engine checks are green. I found no additional material issue in this PR.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Changelog uses issue not PR

Low Severity

The new Unreleased MOD changelog bullet ends with an issue URL (issues/1747) rather than a PR link. New engine changelog entries need a pull/NNNN link; an issue-only reference is not a substitute, so this item does not match the rest of the Unreleased section.

 

^{Triggered by learned rule: CHANGELOG bullets need a PR link}

^{Reviewed by Cursor Bugbot for commit 45126e0. Configure here.}

[sequba]

getRegisteredFunctionNames should still list ALL functions

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

^{Reviewed by Cursor Bugbot for commit 67432bc. Configure here.}

[cursor]

3.4.0 changelog not mirrored

Medium Severity

The published 3.4.0 section now has a retroactive Removed bullet, but docs/guide/release-notes.md still has the original 3.4.0 notes. Those files are release-time mirrors, so a released-version edit in only one of them ships inconsistent notes.

 

^{Triggered by learned rule: Keep CHANGELOG.md and release-notes.md in sync}

^{Reviewed by Cursor Bugbot for commit 67432bc. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.39%. Comparing base (f782d0e) to head (fab1a6f).

Additional details and impacted files

@@                        Coverage Diff                        @@
##           hf-307-entitlement-gating-pr3    #1743      +/-   ##
=================================================================
- Coverage                          97.39%   97.39%   -0.01%     
=================================================================
  Files                                204      204              
  Lines                              16267    16266       -1     
  Branches                            3596     3564      -32     
=================================================================
- Hits                               15844    15843       -1     
  Misses                               415      415              
  Partials                               8        8              

Files with missing lines	Coverage Δ
src/HyperFormula.ts	99.76% <100.00%> (+<0.01%)	⬆️
src/interpreter/FunctionRegistry.ts	100.00% <ø> (ø)

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