Metadata-Version: 2.4
Name: xlodit
Version: 0.1.0
Summary: Validator/debugger for .xlsx workbooks
Project-URL: Homepage, https://github.com/placerte/xlodit
License: MIT License
        
        Copyright (c) 2026
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: audit,cli,excel,traceback,validation,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: rich>=13.7.0
Description-Content-Type: text/markdown

# xlodit

`xlodit` audits `.xlsx` workbooks and emits deterministic machine-readable reports.

## Scope
- Detects formula errors and formula error datatypes
- Detects numeric values stored as text (regex-based)
- Runs minimal structural checks
- Builds traceback trees for failing formula cells
- Read-only: never mutates the input workbook

## Install / Run
From PyPI:

```bash
pip install xlodit
```

Use `uv` during development:

```bash
uv run xlodit path/to/workbook.xlsx
```

By default, `xlodit` prints a Rich terminal report and writes a JSON dump to `<filepath>.xlodit.json`.
Use `--format json` to print JSON to stdout. Terminal output uses `rich` for improved formatting.

## CLI
```bash
uv run xlodit <filepath> [--backend auto|libreoffice|none] [--format terminal|json] [--output path] [--max-traceback-depth N]
```

Use `--help` to see full option descriptions and defaults.

## Exit Codes
- `0`: audit completed and no errors
- `1`: audit completed and at least one error
- `2`: tool/runtime failure

## Limitations
- `.xlsx` only
- No `.xlsm` / `.ods`
- No macro/VBA analysis
- No formatting/chart/pivot validation
- No workbook mutation or auto-fix
- No full Excel formula engine

## License
MIT

## JSON Output
Primary output format is canonical JSON:

- Stable key ordering
- Deterministic issue ordering (severity, sheet, cell, rule)

You can write JSON output to a file with `--output`.

## Agentic Use
- Deterministic JSON ordering for reliable diffs
- Stable rule IDs and issue kinds
- Exit codes map cleanly to success, error, or runtime failure

## Example
```bash
uv run xlodit sample.xlsx --format json --output report.json
```

```bash
uv run xlodit sample.xlsx --format terminal
```

## API
Programmatic use is available via `audit_workbook`:

```python
from xlodit import audit_workbook

report = audit_workbook("/path/to/workbook.xlsx", backend="auto", max_traceback_depth=10)
report_dict = report.to_dict()
```

Key fields in the JSON report:

- `ok`: boolean success indicator
- `audit_completed`: whether the audit finished without runtime failure
- `backend`: backend details (requested, used, recalculated)
- `summary`: counts for errors, warnings, total
- `issues`: list of issues with `severity`, `kind`, `rule_id`, `message`, and location fields

For `formula_error` issues, `traceback` includes a tree of referenced cells. Each node has `sheet`, `cell`, `failing`, optional `value`, and `children` for upstream dependencies.
