Tools: HF-24 snippet codegen — close O5 docs↔test source-of-truth gap

marcin-kordas-hoc · marcin-kordas-hoc · commit 6a441b310785 · 2026-05-25T04:53:44.000Z
Adds the build infrastructure to keep the `customStringifyCurrency` adapter (and any future documented snippet) in lockstep between docs/guide/currency-handling.md and downstream test/utility code. Why this exists: The O5 pattern that HF-24 itself surfaced (Bugbot wave 1, commit b81d4af) was a docs adapter gaining a `typeof !== 'string'` guard while an inline copy in test/.../function-text.spec.ts stayed out of date — edge tests then crashed on `null.split(';')`. Manual "synchronize on every edit" doesn't survive contact with reality. What this lands: - `script/extract-doc-snippets.js` — walks docs/**/*.md, extracts every `` ... `` block (fenced code inside), writes verbatim to test-utils/snippets/<NAME>.generated.ts with a header banner. Zero npm deps; runs in the same Node we use for `compile`. - `npm run snippets:extract` — regenerates all snippets. - `npm run snippets:check` — extracts + `git diff --exit-code` on the output dir, so CI can gate against drift in a single command. - docs/guide/currency-handling.md — adapter wrapped in `snippet:currency-adapter` markers (cosmetic-only edit; the rendered docs are unchanged because VuePress treats `` as a comment). - test-utils/snippets/currency-adapter.generated.ts — initial extraction committed so downstream callers can `import { customStringifyCurrency }` from a stable path. What's deferred (follow-up PR in hyperformula-tests): - Switch test/hyperformula-tests/unit/interpreter/function-text.spec.ts to `import { customStringifyCurrency } from '../../../../<repo>/test-utils/snippets/currency-adapter.generated'` instead of re-defining the adapter inline. That closes the fixture-flagged O5 finding for good; doing it in this PR would mix cross-repo changes and complicate review. - CI integration: a `npm run snippets:check` step in the lint/test workflow. Trivial follow-up once the marker convention lands. Single-source-of-truth direction: documentation. Edit the markdown snippet, run `npm run snippets:extract`, commit the regenerated file — or let CI catch the drift.
diff --git a/docs/guide/currency-handling.md b/docs/guide/currency-handling.md
@@ -108,6 +108,7 @@ If your callback throws, HyperFormula propagates the exception. Wrap your format
 
 This adapter handles a representative subset of Excel currency format strings using native [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat). Extend the `LCID_TO_LOCALE` map to cover more locales — see the [MS-LCID](https://learn.microsoft.com/openspecs/windows_protocols/ms-lcid) specification for canonical identifiers.
 
+<!-- snippet:currency-adapter -->
 ```javascript
 // Minimal Excel-format-string → Intl.NumberFormat adapter.
 // Extend the LCID_TO_LOCALE map and CURRENCY_RULES list to cover more formats.
@@ -182,6 +183,7 @@ export const customStringifyCurrency = (value, currencyFormat) => {
   return undefined
 }
 ```
+<!-- /snippet:currency-adapter -->
 
 Then plug it into your [configuration options](configuration-options.md):
 
diff --git a/package.json b/package.json
@@ -60,6 +60,8 @@
     "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",
+    "snippets:check": "node script/extract-doc-snippets.js && git diff --exit-code -- test-utils/snippets/",
     "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",
diff --git a/script/extract-doc-snippets.js b/script/extract-doc-snippets.js
@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * extract-doc-snippets.js — extract documented code snippets so tests can
+ * import the same source-of-truth the docs publish.
+ *
+ * Walks `docs/**\/*.md`. For every snippet block of the form
+ *
+ *     <!-- snippet:NAME -->
+ *     ```<lang>
+ *     // code …
+ *     ```
+ *     <!-- /snippet:NAME -->
+ *
+ * writes the code (verbatim) to `test-utils/snippets/<NAME>.generated.ts` with
+ * a header banner naming the source file. Tests then `import { … }` from the
+ * generated file instead of re-defining the snippet inline; CI gates drift via
+ * `npm run snippets:extract && git diff --exit-code -- test-utils/snippets/`.
+ *
+ * The script intentionally has zero npm deps so it runs in the same Node we
+ * use for `compile` without adding to package.json.
+ *
+ * Exit codes:
+ *   0 — snippets extracted successfully
+ *   1 — duplicate snippet name across files, mismatched markers, or other
+ *       structural error
+ */
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const REPO_ROOT = path.resolve(__dirname, '..')
+const DOCS_DIR = path.join(REPO_ROOT, 'docs')
+const OUT_DIR = path.join(REPO_ROOT, 'test-utils', 'snippets')
+
+/** Recursively list every `.md` file under `dir`. */
+function listMarkdown(dir) {
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...listMarkdown(p))
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(p)
+  }
+  return out
+}
+
+/** Parse a markdown file and yield { name, lang, code, sourceFile, line }. */
+function * extractSnippets(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8')
+  const lines = text.split('\n')
+  const openRe = /^<!--\s*snippet:([a-zA-Z][a-zA-Z0-9_-]*)\s*-->\s*$/
+  const closeRe = /^<!--\s*\/snippet:([a-zA-Z][a-zA-Z0-9_-]*)\s*-->\s*$/
+  const fenceRe = /^```([a-zA-Z0-9]*)\s*$/
+
+  let i = 0
+  while (i < lines.length) {
+    const openMatch = openRe.exec(lines[i])
+    if (!openMatch) { i++; continue }
+
+    const name = openMatch[1]
+    const startLine = i + 1
+    let j = i + 1
+    // Skip blank lines between marker and fence.
+    while (j < lines.length && lines[j].trim() === '') j++
+    const fenceOpen = fenceRe.exec(lines[j])
+    if (!fenceOpen) {
+      throw new Error(`${filePath}:${startLine} — snippet:${name} marker not followed by a fenced code block`)
+    }
+    const lang = fenceOpen[1] || 'ts'
+    const codeStart = j + 1
+    let k = codeStart
+    while (k < lines.length && !/^```\s*$/.test(lines[k])) k++
+    if (k >= lines.length) {
+      throw new Error(`${filePath}:${startLine} — snippet:${name} fence opened but never closed`)
+    }
+    // Find closing snippet marker after the fence close.
+    let m = k + 1
+    while (m < lines.length && lines[m].trim() === '') m++
+    const closeMatch = m < lines.length ? closeRe.exec(lines[m]) : null
+    if (!closeMatch) {
+      throw new Error(`${filePath}:${startLine} — snippet:${name} missing closing <!-- /snippet:${name} --> after fence`)
+    }
+    if (closeMatch[1] !== name) {
+      throw new Error(`${filePath}:${m + 1} — close marker /snippet:${closeMatch[1]} does not match open snippet:${name}`)
+    }
+
+    yield {
+      name,
+      lang,
+      code: lines.slice(codeStart, k).join('\n'),
+      sourceFile: path.relative(REPO_ROOT, filePath),
+      line: startLine,
+    }
+    i = m + 1
+  }
+}
+
+/** Render the generated file with a stable header banner. */
+function render({ name, lang, code, sourceFile, line }) {
+  const banner = [
+    '// Auto-generated by script/extract-doc-snippets.js — DO NOT EDIT.',
+    `// Source: ${sourceFile}:${line} (snippet:${name})`,
+    '// Edit the source markdown then run `npm run snippets:extract`.',
+    '// CI fails if this file drifts from the source.',
+    '',
+  ].join('\n')
+  // Snippets in docs are JS for readability; the generated `.ts` file consumes
+  // them as TypeScript. Preserve the original content byte-for-byte.
+  return banner + code + (code.endsWith('\n') ? '' : '\n')
+}
+
+function main() {
+  if (!fs.existsSync(DOCS_DIR)) {
+    console.error(`extract-doc-snippets: docs dir not found at ${DOCS_DIR}`)
+    process.exit(1)
+  }
+  fs.mkdirSync(OUT_DIR, { recursive: true })
+
+  const seen = new Map()
+  const written = []
+  for (const file of listMarkdown(DOCS_DIR)) {
+    for (const snippet of extractSnippets(file)) {
+      if (seen.has(snippet.name)) {
+        const prev = seen.get(snippet.name)
+        console.error(`extract-doc-snippets: duplicate snippet name "${snippet.name}"`)
+        console.error(`  first:  ${prev.sourceFile}:${prev.line}`)
+        console.error(`  second: ${snippet.sourceFile}:${snippet.line}`)
+        process.exit(1)
+      }
+      seen.set(snippet.name, snippet)
+      const outPath = path.join(OUT_DIR, `${snippet.name}.generated.ts`)
+      fs.writeFileSync(outPath, render(snippet))
+      written.push(path.relative(REPO_ROOT, outPath))
+    }
+  }
+
+  if (written.length === 0) {
+    console.log('extract-doc-snippets: no <!-- snippet:NAME --> blocks found')
+    return
+  }
+  console.log(`extract-doc-snippets: wrote ${written.length} file(s)`)
+  for (const w of written) console.log(`  ${w}`)
+}
+
+main()
diff --git a/test-utils/snippets/currency-adapter.generated.ts b/test-utils/snippets/currency-adapter.generated.ts
@@ -0,0 +1,76 @@
+// Auto-generated by script/extract-doc-snippets.js — DO NOT EDIT.
+// Source: docs/guide/currency-handling.md:111 (snippet:currency-adapter)
+// Edit the source markdown then run `npm run snippets:extract`.
+// CI fails if this file drifts from the source.
+// Minimal Excel-format-string → Intl.NumberFormat adapter.
+// Extend the LCID_TO_LOCALE map and CURRENCY_RULES list to cover more formats.
+
+const LCID_TO_LOCALE = {
+  '-409': { locale: 'en-US', currency: 'USD' },  // USD
+  '-2':   { locale: 'de-DE', currency: 'EUR' },  // EUR (generic)
+  '-411': { locale: 'ja-JP', currency: 'JPY' },  // JPY
+  '-415': { locale: 'pl-PL', currency: 'PLN' },  // PLN
+  '-809': { locale: 'en-GB', currency: 'GBP' },  // GBP
+}
+
+const CURRENCY_RULES = [
+  // [$SYMBOL-LCID] #,##0[.00] — Excel's locale-tagged currency
+  {
+    pattern: /^\[\$([^\-\]]*)-([0-9A-Fa-f]+)\]\s*#,##0(\.0+)?$/,
+    build: (match) => {
+      const lcid = '-' + match[2]
+      const fractionDigits = (match[3] || '.').length - 1
+      const entry = LCID_TO_LOCALE[lcid] || { locale: 'en-US', currency: 'USD' }
+      return new Intl.NumberFormat(entry.locale, {
+        style: 'currency',
+        currency: entry.currency,
+        minimumFractionDigits: fractionDigits,
+        maximumFractionDigits: fractionDigits,
+      })
+    },
+  },
+  // $#,##0.00 — USD shorthand
+  {
+    pattern: /^\$#,##0(\.0+)?$/,
+    build: (match) => new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: 'USD',
+      minimumFractionDigits: (match[1] || '.').length - 1,
+      maximumFractionDigits: (match[1] || '.').length - 1,
+    }),
+  },
+]
+
+// Accounting: $#,##0.00;($#,##0.00) — positive;negative with parentheses
+function tryAccountingFormat(value, format) {
+  const sections = format.split(';')
+  if (sections.length !== 2) return undefined
+  const isNegative = value < 0
+  const section = sections[isNegative ? 1 : 0]
+  const parenMatch = /^\(\$#,##0(\.0+)?\)$/.exec(section)
+  const plainMatch = /^\$#,##0(\.0+)?$/.exec(section)
+  if (!parenMatch && !plainMatch) return undefined
+  const fractionDigits = ((parenMatch || plainMatch)[1] || '.').length - 1
+  const nf = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: fractionDigits,
+    maximumFractionDigits: fractionDigits,
+  })
+  const formatted = nf.format(Math.abs(value))
+  return isNegative && parenMatch ? `(${formatted})` : formatted
+}
+
+export const customStringifyCurrency = (value, currencyFormat) => {
+  if (typeof currencyFormat !== 'string') return undefined
+  const accounting = tryAccountingFormat(value, currencyFormat)
+  if (accounting !== undefined) return accounting
+
+  for (const rule of CURRENCY_RULES) {
+    const match = rule.pattern.exec(currencyFormat)
+    if (match) return rule.build(match).format(value)
+  }
+  // Not a recognized currency format — let HyperFormula fall through
+  // to the built-in number formatter.
+  return undefined
+}
