# REA Artifact Budget Auditor (Click + Pandas)

## PURPOSE
In the video the reverse-engineering session ends with a workspace "around **1.5 GB**": the
unpacked Loom app, a WSL copy, the **Ghidra** project files, and all the decompiled code that
was generated along the way. Separately, the creator hits a hard wall — the full Loom app is
**532 MB** and REA refused to run on a target that large, so he had to fall back to "Loom's own
app code." This CLI tool turns those two facts into a practical instrument: it walks an
analysis workspace, measures where the bytes actually go, and warns *before* a target blows
past the analyzer's size ceiling.

## WHY THIS MATTERS
Students learn to treat reverse-engineering as an engineering discipline with real resource
limits, not magic. The video is explicit that REA is bounded by target size, and that evidence
(disassembly, traces, bundles) accumulates fast. Knowing your disk budget and your target's
size is the difference between a completed analysis and a failed job.

## HOW TO BUILD
1. `pip install click pandas`.
2. `scan` command: walk a workspace root with `pathlib`, record each file's `size_mb`,
   `.suffix`, and its best-guess `category` (`unpacked_app`, `decompiled`, `ghidra`, `wsl_copy`).
3. Load the inventory into a pandas `DataFrame` and aggregate by category — the exact
   breakdown of that 1.5 GB.
4. `check` command: compare one target's size against a configurable ceiling (default 300 MB)
   and exit non-zero when it exceeds it, mimicking REA's rejection of the 532 MB app.
5. Emit a Markdown/CSV report so the numbers can be pasted into a video breakdown.

```python
frame = pd.DataFrame(rows)  # columns: path, size_mb, suffix, category
budget = frame.groupby("category")["size_mb"].sum().sort_values(ascending=False)
over = frame[frame.size_mb > ceiling_mb]
```

## WHEN TO USE IN PRODUCTION
Use it before kicking off any large analysis job (capacity planning), when cleaning up stale
Ghidra/unpack directories, and in CI to fail a pipeline if an artifact workspace balloons.
Do **not** use it as a security scanner or an evidence-integrity tool — it counts bytes, it does
not validate provenance or trust.

## HOW IT HELPS STUDENTS
They practise Click command design, streaming large directory walks, and pandas group-by
reporting — plus the habit of budgeting resources before a long-running job, which is exactly
what the creator had to reason about mid-session.

## STARTER CODE
See `starter/main.py` for the `scan`, `check`, and `report` commands with a deterministic
sample inventory when no workspace is supplied.
