HF-249 bullet 3: generate built-in functions docs from the HF API (single source of truth)

[marcin-kordas-hoc]

HF-249 bullet 3 — build the docs functions table from HyperFormula (single source of truth)

Third in-scope bullet of HF-249: the built-in functions table in docs/guide/built-in-functions.md is now generated from the public API (getAvailableFunctions / getFunctionDetails) instead of being hand-maintained, so function data lives in one place.

What's here

• Pure render core in src/interpreter/functionMetadata/ (browser-safe, not exported from the package index): formatFunctionSyntax (reuses the reviewed syntax convention), renderBuiltinFunctionsTable, spliceFunctionsTable.
• Dev-only generator scripts/generate-builtin-functions-doc.ts (excluded from the npm package via tsconfig include:["src"]): sources data only from the API, splices the table between AUTOGENERATED:FUNCTIONS markers; hand-written prose and footnote defs stay outside. Deterministic (pinned Intl.Collator, LF, byte-idempotent).
• Per-function anchors (<a id="canonicalName">) on every row — deep-linkable, ready to back documentationUrl.
• OFFSET and VERSION surfaced via the metadata API — per the decision that the docs must document them (users can use them, so the Formula Builder must know them). getAvailableFunctions/getFunctionDetails now return them; the table has 418 functions.
• Drift gate: npm run docs:functions:check (byte-drift + Function-ID membership) wired into the build-docs CI workflow before the docs build; npm run docs:generate-functions regenerates.
• CHANGELOG + DEV_DOCS updated.

Verification

• Full unit suite green; npm run docs:build clean; verify:typings + lint clean; drift check green in-sync.
• Paired tests: hyperformula-tests branch feature/hf-249-docs-single-source.

Base: feature/hf-249-function-metadata-api (ships together with the HF-249 API in #1692).

---

Note

Medium Risk
Expands the public function-metadata API (protected ids) and replaces a large hand-maintained doc with generated output; runtime formula behavior is largely unchanged, but API consumers and docs must stay in sync via the new check.

Overview
The built-in functions guide no longer maintains a hand-written table: content between AUTOGENERATED:FUNCTIONS markers in built-in-functions.md is produced by npm run docs:generate-functions, which calls getAvailableFunctions / getFunctionDetails and splices markdown via renderBuiltinFunctionsTable. npm run docs:functions:check runs in the build-docs workflow so CI fails on stale output or changed function membership.

The metadata API now lists protected OFFSET and VERSION (catalogue entries + PROTECTED_FUNCTION_METADATA, early resolution in resolveFunctionMetadata, and getListableFunctionIds on static and instance registries), so the generated docs match what users can call. Rows gain per-function anchors and syntax strings from formatFunctionSyntax.

DEV_DOCS and CHANGELOG document the single-source-of-truth workflow.

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

[qunabu]

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

[github-actions]

Performance comparison of head (4b5ef17) vs base (8207bf3)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 490.72 |  500.6 | +2.01%
                                      Sheet B | 156.29 | 158.91 | +1.68%
                                      Sheet T | 138.71 | 139.84 | +0.81%
                                Column ranges | 465.63 | 474.28 | +1.86%
Sheet A:  change value, add/remove row/column |  14.57 |  15.66 | +7.48%
 Sheet B: change value, add/remove row/column | 125.85 | 131.43 | +4.43%
                   Column ranges - add column | 148.34 | 144.28 | -2.74%
                Column ranges - without batch |  444.7 | 451.88 | +1.61%
                        Column ranges - batch | 118.79 | 111.47 | -6.16%

[marcin-kordas-hoc]

Paired tests PR: handsontable/hyperformula-tests#19

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.18%. Comparing base (8207bf3) to head (4b5ef17).

Additional details and impacted files

@@                           Coverage Diff                            @@
##           feature/hf-249-function-metadata-api    #1699      +/-   ##
========================================================================
+ Coverage                                 97.17%   97.18%   +0.01%     
========================================================================
  Files                                       192      195       +3     
  Lines                                     15446    15499      +53     
  Branches                                   3412     3422      +10     
========================================================================
+ Hits                                      15009    15063      +54     
+ Misses                                      437      436       -1     

Files with missing lines	Coverage Δ
src/HyperFormula.ts	99.63% <100.00%> (+<0.01%)	⬆️
src/interpreter/FunctionRegistry.ts	100.00% <100.00%> (+0.58%)	⬆️
...rpreter/functionMetadata/categories/information.ts	100.00% <ø> (ø)
...unctionMetadata/categories/lookup-and-reference.ts	100.00% <ø> (ø)
...terpreter/functionMetadata/formatFunctionSyntax.ts	100.00% <100.00%> (ø)
...eter/functionMetadata/protectedFunctionMetadata.ts	100.00% <100.00%> (ø)
...er/functionMetadata/renderBuiltinFunctionsTable.ts	100.00% <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.