HF-307: align getRegisteredFunctionNames with the license gate, deprecate its static form (9/9)

[marcin-kordas-hoc]

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
Public listing API now filters by license and translation snapshot, which can shrink picker lists for restricted keys. Static getRegisteredFunctionNames is deprecated, not removed.

Overview
Makes instance getRegisteredFunctionNames() match what the engine can actually evaluate, so a function picker no longer offers names that would return #LIC!.

It now uses getListableFunctionIds() (so protected built-ins like OFFSET appear), filters with the same licenseListsFunction rule as getAvailableFunctions(), and translates via the instance’s translationPackage snapshot. A missing, invalid, or expired key still does not shorten the list.

Static HyperFormula.getRegisteredFunctionNames() is deprecated (not removed): it has no engine/key in scope. Docs and changelog cover the three listing methods and the migration path (buildEmpty({ language }).getRegisteredFunctionNames()). FunctionRegistry.getRegisteredFunctionIds() is dropped as unused.

^{Reviewed by Cursor Bugbot for commit dcf9354. 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	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	dcf9354	Commit Preview URL Branch Preview URL	Aug 21 2026, 02:18 AM

[github-actions]

Performance comparison of head (dcf9354) vs base (4c8258e)

                                     testName |    base |    head | change
--------------------------------------------------------------------------
                                      Sheet A |  492.23 |  487.43 | -0.98%
                                      Sheet B |  158.66 |  153.56 | -3.21%
                                      Sheet T |  136.79 |  135.68 | -0.81%
                                Column ranges |  467.73 |   471.4 | +0.78%
                                Sorted lookup | 14168.5 | 14212.9 | +0.31%
Sheet A:  change value, add/remove row/column |   14.79 |   14.48 | -2.10%
 Sheet B: change value, add/remove row/column |  125.91 |  130.51 | +3.65%
                   Column ranges - add column |  141.13 |  142.06 | +0.66%
                Column ranges - without batch |  446.51 |  447.68 | +0.26%
                        Column ranges - batch |  111.11 |  112.84 | +1.56%

[codecov]

Codecov Report

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

Additional details and impacted files

@@                    Coverage Diff                    @@
##           hf-329-token-dialects    #1743      +/-   ##
=========================================================
- Coverage                  97.39%   97.39%   -0.01%     
=========================================================
  Files                        204      204              
  Lines                      16253    16252       -1     
  Branches                    3483     3483              
=========================================================
- Hits                       15829    15828       -1     
  Misses                       424      424              

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.