bilig

Evaluate XLSX formula recalculation

Use this when you have an .xlsx file. The check is whether Node can edit known input cells, recalculate formulas, write a new XLSX, and return proof without opening Excel, LibreOffice, or a browser UI.

One command

npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc --demo --json

Expected proof

The current demo prints this shape:

{
  "mode": "demo",
  "input": "generated demo workbook",
  "output": "bilig-formula-recalc-demo.xlsx",
  "edits": 2,
  "externalWorkbooks": 0,
  "reads": {
    "Summary!B2": {
      "tag": 1,
      "value": 72000
    }
  },
  "warnings": [],
  "commandSucceeded": true,
  "recalculationCompleted": true,
  "excelParity": "not_proven",
  "expectedReadback": {
    "Summary!B2": 72000
  },
  "expectedValueMatched": true
}

The exact output file name can change if you pass your own --out path. The important checks are commandSucceeded: true, recalculationCompleted: true, an empty or understood warnings array, and the recalculated cell value under reads. expectedValueMatched: true is only a demo-fixture check. It is not an Excel parity claim; real workbooks still report excelParity: "not_proven" unless you compare against your own Excel, LibreOffice, or Graph oracle.

The JSON contains proof fields only. Star, release-watch, and adoption-blocker links stay in prose so machine output stays usable in CI and agents.

Inspect your workbook first

If you already have the workbook but do not know the right output cells yet, start with inspection:

npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor pricing.xlsx --json

That command does not write pricing.recalculated.xlsx. It imports the workbook, lists formula cells, recomputes every formula by default, reports stale cached values, and suggests --read targets for the real proof command. If you intentionally pass --inspect-limit, require uninspectedFormulaCellCount: 0 before treating the report as complete coverage.

Expected shape:

{
  "formulaCellCount": 12,
  "inspectedFormulaCellCount": 12,
  "uninspectedFormulaCellCount": 0,
  "inspectionLimit": "all",
  "staleCachedFormulaCount": 3,
  "cacheStatusSummary": {
    "inspected": 12,
    "stale": 3,
    "fresh": 9,
    "missingCache": 0,
    "unsupportedRecalculation": 0
  },
  "suggestedReads": ["Summary!B7"],
  "formulas": [
    {
      "target": "Summary!B7",
      "formula": "=Inputs!B2*Inputs!B3",
      "cachedValue": 60000,
      "literalRecalculatedValue": 72000,
      "cacheStatus": "stale",
      "staleCachedValue": true
    }
  ],
  "commandSucceeded": true,
  "inspectionCompleted": true,
  "recalculationCompleted": true,
  "excelParity": "not_proven"
}

Try your workbook

npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc pricing.xlsx \
  --set Inputs!B2=48 \
  --set Inputs!B3=1500 \
  --read Summary!B7 \
  --out pricing.recalculated.xlsx \
  --json

Use sheet-qualified A1 references. Keep your adapter strict: known input cells, known output cells, and tests around the exported workbook.

Put it in CI

Use the repository action when stale cached formula values should block a pull request:

- uses: proompteng/bilig@v1
  with:
    workbook: fixtures/pricing.xlsx
    fail-on-stale: 'true'

The action writes JSON and Markdown reports, adds a job summary, and exposes formula-count, stale-count, uninspected-count, suggested-reads, json, and markdown outputs. See XLSX Cache Doctor GitHub Action, also published on GitHub Marketplace at https://github.com/marketplace/actions/xlsx-cache-doctor.

What this proves

What this does not prove

This is not a claim of complete Excel parity. It does not prove macros, pivots, charts, unsupported formulas, locale-specific Excel behavior, external-link freshness, or exact desktop Excel UI behavior. Keep a golden workbook fixture and an Excel or LibreOffice oracle test for customer-critical file flows.

After the proof