fix(metadata): guard getAvailableFunctions against invalid locale codes (HF-249)

[sequba]

Context

Addresses a code-review finding on #1692: getAvailableFunctions can throw a RangeError for a caller-registered, malformed language code.

buildAvailableFunctions built its sort collator with new Intl.Collator(toBcp47Locale(code)). toBcp47Locale only hyphenates the canonical <ll><RR> shape and passes any other string through unchanged, and registerLanguage performs no shape validation on the code. Intl.Collator throws a RangeError on a structurally invalid language tag (it does not silently fall back to the default locale). So a caller who registers an underscore-style code such as 'pt_BR' (or 'en_US', 'x', '12') and then calls getAvailableFunctions (static or instance) crashes.

Built-in language codes are all safe, so this only affects consumer-registered malformed codes → important, not critical.

The toBcp47Locale JSDoc was also wrong: it claimed unrecognized tags "fall back to the default locale," which Intl.Collator does not do for invalid tags.

Fix

• Extract createLocaleCollator(languageCode) which wraps the Intl.Collator construction in a try/catch and falls back to the environment-default collator (new Intl.Collator()) on RangeError, so listing functions never crashes on a non-BCP-47 code.
• Use it in buildAvailableFunctions.
• Correct the toBcp47Locale JSDoc to describe the real behavior (invalid tags throw; the throw is handled by createLocaleCollator).

getFunctionDetails is unaffected — it does not sort and never constructs a collator.

How did you test your changes?

• Reproduced the crash before the fix: registering 'pt_BR' then calling getAvailableFunctions('pt_BR') threw RangeError: Incorrect locale information provided.
• After the fix, 'pt_BR', 'en_US', 'x', and '12' each return the full, alphabetically-sorted 419-entry list; well-formed 'enGB' is unchanged.
• Confirmed via Node that new Intl.Collator('pt_BR'|'en_US'|'x'|'12') throw while 'zz-ZZ'/'qqq' do not.
• tsc --noEmit clean; eslint src/HyperFormula.ts 0 errors; test/smoke.spec.ts 4/4.

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. Follow-up to Function metadata API: getAvailableFunctions / getFunctionDetails (HF-249) #1692 (HF-249); targets that branch.

Notes for reviewers

• Behavior on a malformed code is now "sort using the default collator" rather than throwing. The alternative (validating codes in registerLanguage) would be a broader, potentially breaking change, so it's intentionally out of scope here.
• A unit test for this belongs in the paired private suite (hyperformula-tests): register a 'pt_BR'-style code and assert getAvailableFunctions returns a sorted list instead of throwing.

  

[qunabu]

Task linked: HF-249 HF function documentation available via API

[github-actions]

Performance comparison of head (368bc15) vs base (18d4246)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 496.13 | 501.97 | +1.18%
                                      Sheet B | 158.85 | 162.28 | +2.16%
                                      Sheet T | 141.15 | 144.72 | +2.53%
                                Column ranges | 469.17 | 478.08 | +1.90%
Sheet A:  change value, add/remove row/column |  15.65 |  16.06 | +2.62%
 Sheet B: change value, add/remove row/column | 129.53 | 131.59 | +1.59%
                   Column ranges - add column | 142.96 | 145.67 | +1.90%
                Column ranges - without batch | 438.38 | 454.61 | +3.70%
                        Column ranges - batch | 115.28 | 114.15 | -0.98%

[codecov]

Codecov Report

❌ Patch coverage is 0% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.59%. Comparing base (18d4246) to head (368bc15).
⚠️ Report is 1 commits behind head on feature/hf-249-function-metadata-api.

Files with missing lines	Patch %	Lines
src/HyperFormula.ts	0.00%	5 Missing ⚠️

Additional details and impacted files

@@                           Coverage Diff                            @@
##           feature/hf-249-function-metadata-api    #1710      +/-   ##
========================================================================
+ Coverage                                 96.42%   96.59%   +0.16%     
========================================================================
  Files                                       192      192              
  Lines                                     15585    15589       +4     
  Branches                                   3447     3447              
========================================================================
+ Hits                                      15028    15058      +30     
+ Misses                                      557      531      -26     

Files with missing lines	Coverage Δ
src/HyperFormula.ts	92.11% <0.00%> (-7.41%)	⬇️

... and 4 files 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.