// STORAGESHOWER — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

storageshower is a single-binary TUI for disk usage monitoring written in Rust on top of ratatui + crossterm. It paints per-mount usage bars in four styles across 30 builtin cyberpunk palettes, refreshes telemetry (load avg, memory, CPU, swap, processes, uptime, network, battery) on a background thread behind an Arc<Mutex<>>, probes per-device SMART status and per-mount disk I/O throughput against IOKit on macOS and /proc/diskstats on Linux, samples network-filesystem latency with a timed read_dir, drills into mounts with a recursive directory explorer, and ships a live per-channel theme editor that round-trips to a TOML config. 13,635 Rust source lines + 49,922 integration test lines across 1,336 test files; 3,692 test functions total; 8 production + 4 dev direct dependencies (269 in the resolved tree); 252 commits since 2026-03-26.

#SOURCE LAYOUT

Thirteen modules under src/. Largest: ui.rs (rendering) and keys.rs (keyboard dispatch). system.rs hosts every platform probe (IOKit / /proc/diskstats / SMART / network FS latency / sysinfo). app.rs owns the App state machine and refresh loop.

Inline-test rows count lines from each module's #[cfg(test)] mod tests block to EOF. main.rs and lib.rs have no inline tests by design; all behavioral coverage of the binary lives in tests/.

*TEST SURFACE

1,336 integration test files in tests/ plus inline #[cfg(test)] modules in every source file. 3,692 total #[test] functions. Integration tests dominate (3,101 of 3,692) and target whole-binary behavior: CLI parsing, config merge, scan output, drill-down sorting, threshold transitions, palette equivalence.

Inline coverage by module (counted as #[test] attributes inside each #[cfg(test)] mod tests):

Integration test files follow a verbose naming convention — each file documents the scenario in its filename so failing tests are self-describing in CI output:

tests/cli_apply_header_no_bars_no_local_integration.rs
tests/cli_binary_void_walker_deep_net_integration.rs
tests/helpers_format_bytes_72_kib_human_integration.rs
tests/scan_directory_two_hundred_sixty_nine_files_integration.rs
… (1,332 more)

Test fixtures live in src/testutil.rs behind pub(crate) and are exposed only when #[cfg(test)]. End-to-end CLI tests spawn the compiled binary under tempfile-managed config dirs and assert against stdout / stderr / exit code rather than poking internal state.

@SUBSYSTEM BREAKDOWN

Eleven feature subsystems sit between the event loop and the renderer. Every probe is cancellable and bounded so the UI thread never blocks — slow filesystems return None after the deadline and rerun next tick.

%THEME SYSTEM

30 builtin palettes defined as ColorMode variants in src/types.rs. Each maps to a six-channel ThemeColors (blue, green, purple, light_purple, royal, dark_purple) consumed by ui::palette() and ui::palette_for_prefs(). User themes ship as themes/*.toml and merge into the user's ~/.storageshower.conf as [custom_themes.<name>] blocks, activated via active_theme or --theme.

The color_mode_next_cycles_full_palette_exactly test in src/types.rs pins the cycle order. Any new variant added to ColorMode::ALL bumps that test — an immune system against silently dropping a palette.

!PLATFORM PROBES

Every OS-touching code path lives in src/system.rs. The probes are cfg(target_os = "macos") / cfg(target_os = "linux") gated and return uniform types so the rest of the codebase (renderer, alert subsystem, drill-down) is platform-agnostic.

+DEPENDENCIES

Eight direct production dependencies + four dev-dependencies. Cargo.lock resolves to 269 crates total — the bulk are transitive pulls from ratatui (signal handling, terminal backends) and sysinfo (per-OS shims).

Release profile: opt-level = 3, lto = true, strip = true. Rust 2024 edition; MSRV ≥ 1.85. CI matrix targets x86_64-apple-darwin (macos-latest), aarch64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu.

;PUBLIC API SURFACE

src/lib.rs exposes the library so integration tests and the binary share a single compilation unit. Eight pub mods; keys and mouse stay private; testutil is pub(crate) behind #[cfg(test)].

?KEY DESIGN DECISIONS

~BENCHMARK SUITE

benches/bench.rs (344 lines, harness = false) drives a Criterion suite over the hot paths: byte formatting, uptime formatting, mount-name truncation, column-width math, palette resolve, gradient interpolation, time conversion, disk / sys-stat collection, config serde, and the sort / filter / render pipelines at 10 / 50 / 200 disks. Run with cargo bench; HTML reports land in target/criterion/.

Times are Criterion-measured on Apple Silicon (M-series) and reproduced verbatim from the README; absolute figures vary by hardware. The point is the shape: every per-frame path is sub-microsecond, every per-tick path is single-digit microseconds, so the render loop is never the bottleneck.

=CI & RELEASE

GitHub Actions gates every push, pull request, and merge-queue batch to main. All jobs run --locked so CI resolves the exact dependency graph committed in Cargo.lock; concurrent runs for a branch are cancelled when a newer commit lands.

The release workflow builds on tag push for six targets — aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu (cross-compiled), and static x86_64 / aarch64 musl variants — then publishes a GitHub release and regenerates the Homebrew formula in MenkeTechnologies/homebrew-menketech. To match CI locally before pushing:

cargo fmt --all --check \
  && cargo clippy --locked --all-targets -- -D warnings \
  && cargo test --locked --lib \
  && cargo test --locked --tests \
  && cargo test --locked --doc

.REPOSITORY

• Source — github.com/MenkeTechnologies/storageshower
• Crate — crates.io/crates/storageshower
• Homebrew — brew tap MenkeTechnologies/menketech
• API docs — docs.rs/storageshower
• Issues — github.com/MenkeTechnologies/storageshower/issues
• Docs hub — index.html (install, keys, CLI flags, themes)