spreadsheet-auditor 0.1.0__py3-none-any.whl

spreadsheet_auditor/__init__.py

@@ -0,0 +1,13 @@
+"""Audit existing spreadsheets for correctness defects.
+
+`spreadsheet-auditor` is an audit-only Agent Skill and CLI for reviewing
+existing Excel workbooks and financial models. It identifies formula errors,
+broken references, range mistakes, hardcoded values, reconciliation failures,
+circular references, hidden-structure risks, and data-quality issues without
+modifying the source workbook.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

spreadsheet_auditor/__main__.py

@@ -0,0 +1,8 @@
+"""Enable `python -m spreadsheet_auditor` invocation."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spreadsheet_auditor/annotate.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from openpyxl import load_workbook
+from openpyxl.comments import Comment
+
+
+def _anchor_location(location: str) -> tuple[str, str] | None:
+    """Resolve a finding location to a single (sheet, coordinate) anchor cell.
+
+    Handles comma-joined multi-locations (uses the first) and range locations
+    (uses the top-left cell), e.g. "Sheet1!A1:B2" -> ("Sheet1", "A1").
+    """
+    if not location:
+        return None
+    first = location.split(",", 1)[0].strip()
+    if "!" not in first:
+        return None
+    sheet_name, coord = first.split("!", 1)
+    coord = coord.split(":", 1)[0].replace("$", "").strip()
+    if not sheet_name or not coord:
+        return None
+    return sheet_name, coord
+
+
+def annotate_workbook(source_path: str | Path, output_path: str | Path, findings: list[dict]) -> None:
+    source = Path(source_path)
+    keep_vba = source.suffix.lower() == ".xlsm"
+    wb = load_workbook(source, keep_vba=keep_vba)
+    for finding in findings:
+        if finding.get("suppressed"):
+            continue
+        location = finding.get("location", "")
+        anchor = _anchor_location(location)
+        if anchor is None:
+            continue
+        sheet_name, coord = anchor
+        if sheet_name not in wb.sheetnames:
+            continue
+        cell = wb[sheet_name][coord]
+        text = (
+            f"{finding.get('severity')} {finding.get('rule_id')}\n"
+            f"{finding.get('title')}\n"
+            f"Fix: {finding.get('suggested_fix')}"
+        )
+        cell.comment = Comment(text, "Spreadsheet Auditor")
+    wb.save(output_path)