@bilig/xlsx-formula-recalc 0.129.2 → 0.130.1

package/README.md

@@ -4,17 +4,14 @@ Diagnose stale cached XLSX formula values in Node and CI, then recalculate the
 cells your service actually reads without Excel, LibreOffice, or browser
 automation.
 
-This is the canonical scoped Bilig package for the high-friction Node XLSX
-workflow: a file library edits workbook bytes, but the formula cells still carry
-old cached values. Start with the cache doctor when you do not know which cells
-are stale. Use recalculation after the detector points at the cells that matter.
+This package is for the high-friction Node XLSX workflow: a file library edits
+workbook bytes, but the formula cells still carry old cached values. Start with
+the cache doctor when you do not know which cells are stale. Use recalculation
+after the detector points at the cells that matter.
 
 It fits `xlsx-populate`, SheetJS / `xlsx`, template-generation, GitHub Actions,
 and backend file pipelines where stale readback is worse than a hard failure.
 
-The unscoped `xlsx-formula-recalc` package remains published as a compatibility
-and search alias.
-
 ## Try The Cache Doctor First
 
 Run the no-project demo:
@@ -27,6 +24,7 @@ Expected shape:
 
 ```json
 {
+  "schemaVersion": "xlsx-cache-doctor.v1",
   "formulaCellCount": 1,
   "inspectedFormulaCellCount": 1,
   "uninspectedFormulaCellCount": 0,
@@ -56,6 +54,15 @@ Expected shape:
 The JSON is meant for CI and agents. It does not include star, release-watch, or
 discussion links.
 
+If a coding agent needs to edit workbook state instead of only inspecting XLSX
+bytes, do not automate Excel or a browser grid. Run the headless proof:
+
+```sh
+npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json
+```
+
+Then use the [agent MCP evaluator](https://proompteng.github.io/bilig/eval-agent-mcp.html).
+
 Use `cacheStatusSummary` and per-formula `cacheStatus` to separate confirmed
 stale caches from missing cached values or formulas without a comparable
 recalculated value.
@@ -128,6 +135,7 @@ the JSON includes the skipped count as `uninspectedFormulaCellCount`.
 
 ```json
 {
+  "schemaVersion": "xlsx-cache-doctor.v1",
   "formulaCellCount": 12,
   "inspectedFormulaCellCount": 12,
   "uninspectedFormulaCellCount": 0,
@@ -219,6 +227,30 @@ run
 
 ## API
 
+Use `inspectXlsxCache` when a service or test runner needs the cache-doctor
+report without shelling out to the CLI:
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { inspectXlsxCache } from '@bilig/xlsx-formula-recalc'
+
+const report = inspectXlsxCache(await readFile('pricing.xlsx'), {
+  fileName: 'pricing.xlsx',
+})
+
+if (report.staleCachedFormulaCount > 0) {
+  throw new Error(
+    report.formulas
+      .filter((formula) => formula.cacheStatus === 'stale')
+      .map((formula) => formula.target)
+      .join(', '),
+  )
+}
+```
+
+The API returns the same `schemaVersion`, `cacheStatusSummary`, per-formula
+`cacheStatus`, and `suggestedReads` fields as the JSON CLI report.
+
 ```ts
 import { recalculateXlsx } from '@bilig/xlsx-formula-recalc'
 
@@ -296,3 +328,7 @@ external workbook links, macros, and volatile functions may need review. Import
 warnings are returned in `result.warnings`.
 
 Full docs: <https://proompteng.github.io/bilig/xlsx-formula-recalculation-node.html>
+
+Compatibility note: the unscoped `xlsx-formula-recalc` package remains
+published as a search and migration alias. Use `@bilig/xlsx-formula-recalc` in
+new projects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/xlsx-formula-recalc",
-  "version": "0.129.2",
+  "version": "0.130.1",
   "description": "Diagnose stale cached XLSX formula values and recalculate XLSX formulas in Node.js without Excel, LibreOffice, or browser automation.",
   "keywords": [
     "bilig",
@@ -71,7 +71,7 @@
     "smoke": "node ./dist/cli.js --help"
   },
   "dependencies": {
-    "xlsx-formula-recalc": "0.129.2"
+    "xlsx-formula-recalc": "0.130.1"
   },
   "engines": {
     "node": ">=22.0.0"