@bilig/xlsx-formula-recalc 0.155.0 → 0.159.0

package/AGENTS.md

@@ -0,0 +1,84 @@
+# @bilig/xlsx-formula-recalc Agent Notes
+
+Use this package when a Node.js task edits an `.xlsx` workbook and needs fresh
+formula results before returning the file or reading output cells.
+
+Start with the no-project evaluator:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json
+```
+
+Use `workbook-compatibility` when a caller asks whether a specific `.xlsx` is
+safe to use with Bilig before an agent or Node service trusts it. The report is
+an inspector, not a grader: it lists unsupported functions, external links,
+macro payloads, pivots, volatile functions, stale caches, and risk reasons. Do
+not add or claim a compatibility score.
+
+If the task came from a SheetJS / `xlsx` stale-formula issue, the same package
+also exposes a SheetJS-named command:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- sheetjs-recalc --demo --json
+```
+
+If the caller has a real workbook but does not know which formulas to read yet,
+inspect it first without writing an output file:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx --inspect --json
+```
+
+Use the memorable cache-diagnosis alias for issue triage or CI:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor workbook.xlsx --json
+```
+
+Use the workbook compatibility report for preflight risk review:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json
+```
+
+Use the returned `suggestedReads`, stale cached formula counts, warnings, and
+risk reasons to decide the narrow proof command. By default the doctor and
+compatibility report inspect every formula; if a caller passes
+`--inspect-limit`, require `uninspectedFormulaCellCount: 0` before treating the
+report as complete coverage.
+
+For a real workbook, use sheet-qualified A1 targets:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc quote.xlsx \
+  --set Inputs!B2=48 \
+  --read Summary!B7 \
+  --out quote.recalculated.xlsx \
+  --json
+```
+
+For external workbook links, pass companion files with `--external-workbook`
+or exact link bindings with `--external-workbook-target <path> <target>`:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc quote.xlsx \
+  --external-workbook-target ./fixtures/rates-current.xlsx file:///tmp/rates.xlsx \
+  --read Summary!B7 \
+  --json
+```
+
+Use the API when code already has workbook bytes:
+
+```ts
+import { recalculateXlsx } from '@bilig/xlsx-formula-recalc'
+
+const result = recalculateXlsx(xlsxBytes, {
+  edits: [{ target: 'Inputs!B2', value: 48 }],
+  reads: ['Summary!B7'],
+})
+```
+
+Do not claim this is a full Excel clone. Review `result.warnings` and reduce
+unsupported functions, external links, macros, and volatile formula cases into
+fixtures before promising production behavior.

package/README.md

@@ -17,26 +17,39 @@ and backend file pipelines where stale readback is worse than a hard failure.
 Run the no-project evaluator demo:
 
 ```sh
+npx --package @bilig/xlsx-formula-recalc bilig-evaluate --door workbook-compatibility --json
 npx --package @bilig/xlsx-formula-recalc bilig-evaluate --door xlsx-cache --json
 ```
 
+Use `workbook-compatibility` when the question is whether a real workbook has
+known integration risks before a Node service or coding agent trusts Bilig with
+it. The report lists unsupported functions, external links, VBA payloads,
+pivots, volatile functions, stale caches, and concrete `risk.reasons`. It does
+not certify Excel compatibility and it does not print a compatibility score.
+
 Expected evaluator shape:
 
 ```json
 {
   "schemaVersion": "bilig-evaluator.v1",
-  "door": "xlsx-cache",
+  "door": "workbook-compatibility",
   "verified": true,
   "evidence": {
-    "target": "Summary!B2",
-    "before": 60000,
-    "after": 72000,
-    "staleCachedFormulaCount": 1,
-    "suggestedReads": ["Summary!B2"]
+    "riskLevel": "high",
+    "unsupportedFunctions": [{ "name": "CUBEVALUE", "count": 1 }],
+    "volatileFunctions": [{ "name": "NOW", "count": 1 }],
+    "formulaCellCount": 3,
+    "staleCachedFormulaCount": 2
   }
 }
 ```
 
+Run the report directly against a workbook:
+
+```sh
+npx --package @bilig/xlsx-formula-recalc workbook-compatibility-report pricing.xlsx --json
+```
+
 ## Try The Cache Doctor Directly
 
 Run the no-project demo:
@@ -140,6 +153,10 @@ Use this package at the file boundary:
 That keeps your current file-writer choice intact and adds only the missing
 calculation/readback step.
 
+If you are not sure whether the fix belongs at the XLSX file, SheetJS, ExcelJS,
+template, CI, WorkPaper, or agent boundary, start with the
+[stale formula readback chooser](https://proompteng.github.io/bilig/stale-formula-readback-chooser.html).
+
 ## Install
 
 ```sh

package/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: bilig-xlsx-formula-recalc
+version: 0.1.0
+description: Recalculate XLSX formula outputs in Node.js after cell edits without opening Excel, LibreOffice, or browser automation.
+tags:
+  - xlsx
+  - excel
+  - formula-recalculation
+  - node
+  - spreadsheet-automation
+  - typescript
+---
+
+# Bilig XLSX Formula Recalculation
+
+Use `@bilig/xlsx-formula-recalc` when an agent or Node.js service has changed
+XLSX inputs and must read recalculated formula outputs without opening Excel,
+LibreOffice, or a browser. This package is the canonical scoped package.
+
+## First Check
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json
+```
+
+Use `workbook-compatibility` when you need a local preflight report for a real
+workbook before a Node service or agent trusts it. The report lists unsupported
+functions, external links, macro payloads, pivots, volatile functions, stale
+caches, and concrete risk reasons. It does not certify Excel compatibility and
+must not grow a compatibility score.
+
+The cache evaluator should print `schemaVersion: "bilig-evaluator.v1"`,
+`door: "xlsx-cache"`, `verified: true`, and evidence for a stale cached
+formula corrected to a `Summary!B2` value of `72000`.
+
+For SheetJS / `xlsx` stale-formula issues, use the SheetJS-named binary from the
+same package:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- sheetjs-recalc --demo --json
+```
+
+If you have a real workbook but do not yet know which formula cells to verify,
+inspect it without writing an output file:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx --inspect --json
+```
+
+For CI or issue triage, use the cache-diagnosis alias:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor workbook.xlsx --json
+```
+
+For workbook risk review, use the compatibility report:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json
+```
+
+The inspection output includes `formulaCellCount`, `staleCachedFormulaCount`,
+`suggestedReads`, and warnings. Default inspection checks every formula. If a
+workflow sets `--inspect-limit`, require `uninspectedFormulaCellCount: 0` before
+treating the report as complete coverage.
+
+## Real Workbook
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx \
+  --set Inputs!B2=48 \
+  --read Summary!B7 \
+  --out workbook.recalculated.xlsx \
+  --json
+```
+
+For linked workbooks, pass companion files:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx \
+  --external-workbook rates.xlsx \
+  --read Summary!B7 \
+  --json
+```
+
+Use an exact target binding when the workbook link target differs from the local
+filename:
+
+```sh
+npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc workbook.xlsx \
+  --external-workbook-target ./fixtures/rates-current.xlsx file:///tmp/rates.xlsx \
+  --read Summary!B7 \
+  --json
+```
+
+## TypeScript
+
+```ts
+import { recalculateXlsx } from '@bilig/xlsx-formula-recalc'
+
+const result = recalculateXlsx(inputXlsxBytes, {
+  edits: [{ target: 'Inputs!B2', value: 48 }],
+  reads: ['Summary!B7'],
+})
+```
+
+Prefer `exceljs-formula-recalc` when the caller already owns an ExcelJS
+`Workbook` object and wants read results patched back into that object.

package/bin/workbook-compatibility-report.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+await import('../dist/workbook-compatibility-report-cli.js')

package/dist/workbook-compatibility-report-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/workbook-compatibility-report-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runWorkbookCompatibilityReportCli } from 'xlsx-formula-recalc/workbook-compatibility-report';
+process.exitCode = runWorkbookCompatibilityReportCli(process.argv.slice(2));
+//# sourceMappingURL=workbook-compatibility-report-cli.js.map

package/dist/workbook-compatibility-report-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbook-compatibility-report-cli.js","sourceRoot":"","sources":["../src/workbook-compatibility-report-cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,iCAAiC,EAAE,MAAM,mDAAmD,CAAA;AAErG,OAAO,CAAC,QAAQ,GAAG,iCAAiC,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/workbook-compatibility-report.d.ts

@@ -0,0 +1,2 @@
+export * from 'xlsx-formula-recalc/workbook-compatibility-report';
+export type * from 'xlsx-formula-recalc/workbook-compatibility-report';

package/dist/workbook-compatibility-report.js

@@ -0,0 +1,2 @@
+export * from 'xlsx-formula-recalc/workbook-compatibility-report';
+//# sourceMappingURL=workbook-compatibility-report.js.map

package/dist/workbook-compatibility-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbook-compatibility-report.js","sourceRoot":"","sources":["../src/workbook-compatibility-report.ts"],"names":[],"mappings":"AAAA,cAAc,mDAAmD,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilig/xlsx-formula-recalc",
-  "version": "0.155.0",
+  "version": "0.159.0",
   "description": "Diagnose stale cached XLSX formula values and recalculate XLSX formulas in Node.js without Excel, LibreOffice, or browser automation.",
   "keywords": [
     "bilig",
@@ -18,6 +18,8 @@
     "spreadsheet-formulas",
     "stale-xlsx-cache",
     "workbook",
+    "workbook-compatibility-report",
+    "workbook-risk-report",
     "xlsx",
     "xlsx-cache-doctor",
     "xlsx-calc",
@@ -40,12 +42,15 @@
   "bin": {
     "bilig-evaluate": "./bin/bilig-evaluate.js",
     "sheetjs-recalc": "./bin/sheetjs-recalc.js",
+    "workbook-compatibility-report": "./bin/workbook-compatibility-report.js",
     "xlsx-cache-doctor": "./bin/xlsx-cache-doctor.js",
     "xlsx-recalc": "./bin/xlsx-recalc.js"
   },
   "files": [
     "bin",
     "dist",
+    "AGENTS.md",
+    "SKILL.md",
     "README.md",
     "LICENSE"
   ],
@@ -68,6 +73,11 @@
       "types": "./dist/evaluator.d.ts",
       "import": "./dist/evaluator.js",
       "default": "./dist/evaluator.js"
+    },
+    "./workbook-compatibility-report": {
+      "types": "./dist/workbook-compatibility-report.d.ts",
+      "import": "./dist/workbook-compatibility-report.js",
+      "default": "./dist/workbook-compatibility-report.js"
     }
   },
   "publishConfig": {
@@ -78,7 +88,7 @@
     "smoke": "node ./dist/cli.js --help"
   },
   "dependencies": {
-    "xlsx-formula-recalc": "0.155.0"
+    "xlsx-formula-recalc": "0.159.0"
   },
   "engines": {
     "node": ">=22.0.0"