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

CHANGELOG.md

@@ -12,6 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Added the `getAvailableFunctions()` and `getFunctionDetails()` methods (both static and instance) for retrieving function metadata. [#1692](https://github.com/handsontable/hyperformula/pull/1692)
 - Added new functions: VSTACK, HSTACK. [#1698](https://github.com/handsontable/hyperformula/pull/1698)
 - Added a new function: `XIRR`. [#1701](https://github.com/handsontable/hyperformula/pull/1701)
+- The built-in functions guide table is now generated from the function metadata API (single source of truth), and now also documents OFFSET and VERSION. [#1692](https://github.com/handsontable/hyperformula/pull/1692)
 - Added an Indonesian (Bahasa Indonesia) language pack. [#1674](https://github.com/handsontable/hyperformula/pull/1674)
 - Added a `stringifyCurrency` config option that lets you plug in a custom currency formatter for the `TEXT` function. [#1145](https://github.com/handsontable/hyperformula/issues/1145)
 

DEV_DOCS.md

@@ -104,6 +104,12 @@ Adding a built-in function is similar to adding a [custom function](docs/guide/c
 4. Add translations to all language files in `src/i18n/languages/`.
 5. Add tests in `test/unit/interpreter/`.
 
+The built-in functions table in `docs/guide/built-in-functions.md` is generated from HyperFormula's API
+(`getAvailableFunctions`/`getFunctionDetails`). Do not hand-edit the region between the
+`AUTOGENERATED:FUNCTIONS` markers — change the metadata in `src/interpreter/functionMetadata/`. The table is
+regenerated automatically as part of `npm run docs:build` (and `npm run docs:dev`), so the committed snapshot never
+drifts; run `npm run docs:generate-functions` if you want to refresh it on its own.
+
 ## Internationalization and function translations
 
 HyperFormula supports internationalization and provides localized function names for all built-in languages. Translation files live in `src/i18n/languages/`. New functions must include translations for all built-in languages.

package.json

@@ -55,12 +55,13 @@
   "unpkg": "dist/hyperformula.min.js",
   "typings": "./typings/index.d.ts",
   "scripts": {
-    "docs:dev": "npm run typedoc:build-api && cross-env NODE_OPTIONS=--openssl-legacy-provider vuepress dev docs --silent --no-clear-screen --no-cache",
-    "docs:build": "npm run bundle-all && npm run typedoc:build-api && cross-env NODE_OPTIONS=--openssl-legacy-provider vuepress build docs",
+    "docs:dev": "npm run docs:generate-functions && npm run typedoc:build-api && cross-env NODE_OPTIONS=--openssl-legacy-provider vuepress dev docs --silent --no-clear-screen --no-cache",
+    "docs:build": "npm run docs:generate-functions && npm run bundle-all && npm run typedoc:build-api && cross-env NODE_OPTIONS=--openssl-legacy-provider vuepress build docs",
     "docs:code-examples:generate-js": "bash docs/code-examples-generator.sh",
     "docs:code-examples:generate-all-js": "bash docs/code-examples-generator.sh --generateAll",
     "docs:code-examples:format-all-ts": "bash docs/code-examples-generator.sh --formatAllTsExamples",
     "snippets:extract": "node script/extract-doc-snippets.js",
+    "docs:generate-functions": "npm run tsnode scripts/generate-builtin-functions-doc.ts",
     "bundle-all": "cross-env HF_COMPILE=1 npm-run-all clean compile bundle:** verify-bundles",
     "bundle:es": "(node script/if-ne-env.js HF_COMPILE=1 || npm run compile) && cross-env-shell BABEL_ENV=es env-cmd -f ht.config.js babel lib --out-file-extension .mjs --out-dir es",
     "bundle:cjs": "(node script/if-ne-env.js HF_COMPILE=1 || npm run compile) && cross-env-shell BABEL_ENV=commonjs env-cmd -f ht.config.js babel lib --out-dir commonjs",

scripts/generate-builtin-functions-doc.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright (c) 2025 Handsoncode. All rights reserved.
+ */
+
+/**
+ * HF-249 bullet 3 — generates the built-in functions table in `docs/guide/built-in-functions.md` from
+ * HyperFormula's public API (single source of truth). Dev-only; never shipped (`tsconfig.json` `include` is
+ * `["src"]`). Run via `npm run docs:generate-functions`; it also runs as the first step of `docs:build` and
+ * `docs:dev`, so the committed table is regenerated on every build and cannot drift from the catalogue.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import {HyperFormula} from '../src'
+import {renderBuiltinFunctionsTable, spliceFunctionsTable} from '../src/interpreter/functionMetadata/renderBuiltinFunctionsTable'
+
+const REPO_ROOT = path.resolve(__dirname, '..')
+const DOC_PATH = path.join(REPO_ROOT, 'docs/guide/built-in-functions.md')
+const LANGUAGE = 'enGB'
+
+/** Reads the doc file and returns a new version with the generated table region spliced in. */
+function buildUpdatedFile(): string {
+  const entries = HyperFormula.getAvailableFunctions(LANGUAGE)
+  const detailsFor = (canonicalName: string) => HyperFormula.getFunctionDetails(canonicalName, LANGUAGE)
+  const generated = renderBuiltinFunctionsTable(entries, detailsFor)
+  const current = fs.readFileSync(DOC_PATH, 'utf8')
+  return spliceFunctionsTable(current, generated)
+}
+
+/** Regenerates the table region of the doc file from the current catalogue. */
+function main(): void {
+  fs.writeFileSync(DOC_PATH, buildUpdatedFile(), 'utf8')
+  process.stdout.write('built-in-functions.md regenerated.\n')
+}
+
+main()

src/HyperFormula.ts

@@ -48,6 +48,7 @@ import {FunctionPluginDefinition} from './interpreter'
 import {FUNCTION_DOCS} from './interpreter/functionMetadata'
 import {buildCustomFunctionDetails, buildCustomFunctionListEntry, buildFunctionDetails, buildFunctionListEntry, StructuralMetadata} from './interpreter/functionMetadata/buildFunctionDescriptions'
 import {FunctionDetails, FunctionDoc, FunctionListEntry} from './interpreter/functionMetadata/FunctionDescription'
+import {PROTECTED_FUNCTION_METADATA} from './interpreter/functionMetadata/protectedFunctionMetadata'
 import {FunctionRegistry, FunctionTranslationsPackage} from './interpreter/FunctionRegistry'
 import {FormatInfo} from './interpreter/InterpreterValue'
 import {LazilyTransformingAstService} from './LazilyTransformingAstService'
@@ -713,7 +714,16 @@ export class HyperFormula implements TypedEmitter {
     validateArgToType(code, 'string', 'code')
     const plugin = FunctionRegistry.getFunctionPlugin(canonicalName)
     if (plugin === undefined) {
-      return undefined
+      // Protected ids (VERSION, OFFSET) have no registered plugin by design (`getFunctionPlugin` always returns
+      // `undefined` for them), but the metadata API still describes them — resolved from the authored catalogue
+      // doc, so getFunctionDetails agrees with getAvailableFunctions. Anything else with no plugin is genuinely
+      // unknown. `buildFunctionDetailsFor` returns `undefined` for a protected id without a catalogue doc, so the
+      // list and the details stay consistent for those too.
+      if (!FunctionRegistry.functionIsProtected(canonicalName)) {
+        return undefined
+      }
+      const language = this.getLanguage(code)
+      return HyperFormula.buildFunctionDetailsFor(canonicalName, undefined, language)
     }
     // Resolve aliases to their canonical target id before checking built-in ownership
     const canonicalId = plugin.aliases?.[canonicalName] ?? canonicalName
@@ -738,6 +748,16 @@ export class HyperFormula implements TypedEmitter {
    * @param {FunctionPluginDefinition | undefined} plugin - the plugin registered for `functionId`, or `undefined`
    */
   private static resolveFunctionMetadata(functionId: string, plugin: FunctionPluginDefinition | undefined): { doc: FunctionDoc | undefined, metadata: StructuralMetadata } | undefined {
+    // Protected ids (VERSION, OFFSET) are excluded from the plugin registry by design (`getFunctionPlugin` always
+    // returns `undefined` for them), so they would otherwise fall straight into the `plugin === undefined` case
+    // below and disappear from the metadata API. Kuba decided (HF-249) that they must still be described, because
+    // a user can call them from a formula: resolve them here from the authored catalogue doc and structural
+    // metadata instead of from a plugin. A protected id stays unlisted unless BOTH are authored — requiring the
+    // structural metadata keeps `buildFunctionDetails` from reading `repeatLastArgs`/`parameters` off `undefined`
+    // if the two maps ever drift (fail-safe: the function is omitted rather than crashing the metadata API).
+    if (FunctionRegistry.functionIsProtected(functionId) && FUNCTION_DOCS[functionId] !== undefined && PROTECTED_FUNCTION_METADATA[functionId] !== undefined) {
+      return {doc: FUNCTION_DOCS[functionId], metadata: PROTECTED_FUNCTION_METADATA[functionId]}
+    }
     if (plugin === undefined) {
       return undefined
     }