XLSX-Ray

• 

  Git says your Excel file changed. XLSX-Ray tells you what changed — and why it matters.

Problem Statement

Excel workbooks are everywhere in finance, operations, research, planning, and internal tooling, but they remain awkward software artifacts. Put an .xlsx file in Git and a pull request usually cannot tell a reviewer whether the change was a harmless input edit, a rewritten formula, a removed validation rule, a new external link, a protection change, or the introduction of a macro-bearing workbook.

That makes spreadsheet review depend on opening files manually and visually inspecting them — a fragile process for files that may contain business-critical logic.

Solution Overview

XLSX-Ray is a local, read-only command-line tool and GitHub Action that turns workbook changes into deterministic, reviewable evidence.

It inspects selected OOXML facts directly from .xlsx and .xlsm packages and produces Markdown for humans and versioned JSON for automation. It does not calculate formulas, execute VBA, follow external links, upload workbook contents, or modify the workbook.

Instead of treating an Excel file as an opaque binary blob, XLSX-Ray makes supported structural and risk-relevant changes visible in the same review workflow teams already use for code.

Key Features

• Workbook-aware diff: reports worksheet, cell value, formula, defined-name, external-link, validation, protection, and VBA-package changes.
• Explainable risk levels: fixed low / medium / high rules make CI decisions understandable rather than opaque.
• Formula impact evidence: conservatively surfaces reviewer leads from direct A1 references, static range overlap, and scope-safe static defined names without pretending to be a full Excel calculation engine.
• GitHub Action: can write a workbook review into the GitHub Job Summary and fail CI when supported high-risk changes are detected.
• Human + machine output: Markdown reports for review and stable, versioned JSON Schema-backed output for automation.
• Local-first safety boundary: no hosted service, no required API, no formula execution, no macro execution, no workbook mutation.

Technologies Used

• Python 3.10+
• Standard-library ZIP and XML inspection for OOXML packages
• pytest for regression and adversarial tests
• ruff for linting / formatting
• JSON Schema Draft 2020-12 for machine-readable output contracts
• GitHub Actions composite action for CI integration
• openpyxl in development fixtures to validate representative third-party-produced workbooks

XLSX-Ray intentionally has no runtime dependencies beyond Python 3.10+.

Target Users

• engineering teams that keep operational or analytical Excel workbooks in Git;
• finance, operations, research, and data teams whose spreadsheets contain review-worthy logic;
• maintainers who want CI checks around workbook changes without uploading sensitive files to a hosted service;
• developers building spreadsheet-aware review or compliance workflows.

What Makes It Different

Many spreadsheet comparison tools focus on visual or cell-by-cell differences. XLSX-Ray is designed around software review evidence: deterministic package facts, explainable risk, CI behavior, and conservative impact leads.

The product boundary is deliberate. XLSX-Ray does not claim to reproduce Excel, evaluate formulas, prove semantic equivalence, parse macro behavior, or build a complete dependency graph. When it cannot support a claim reliably, it prefers an explicit limitation over a guess.

Current Status

v0.1.0 is publicly released on GitHub. The repository includes a reusable GitHub Action, synthetic demo workbooks, versioned JSON schemas, adversarial parser tests, compatibility and security documentation, and an implementation review that records the project's reliability boundaries.

PyPI publication is still pending and is not required to run the tool; it can be installed from the repository or GitHub release artifacts.

Built With

• github
• json
• openpyxl
• pytest
• python
• ruff
• xml
• zip