htoprs — Engineering Report
Description: htoprs — engineering report. A faithful Rust port of htop 3.5.1. Porting methodology, the build-time port-purity gate, coverage against the C spec, and project metadata.

## >_EXECUTIVE SUMMARY

htoprs is a faithful Rust port of htop 3.5.1, the interactive process viewer. The upstream C source is the specification — the port is translated function-for-function, never reimplemented from scratch, the same precedent as zshrs.

Fidelity is enforced mechanically: a build-time port-purity gate rejects any free `fn` under `src/ported/` whose name has no counterpart in the htop C source. The port now covers 121 of the 131 C files — 891 of 1093 C functions (81.5%), with 31 remaining stubs. On top of the port sits an htoprs-original extensions layer (18 modules, exempt from the port-purity gate) providing a named color-theme system, a keyboard-help/theme overlay, and a live monitoring suite (per-PID history rings, threshold alerts, braille CPU graphs, a fuzzy finder, snapshot diffs, and exporters). Live coverage per file is in the port report.

v0.5.0
Version
3.5.1
htop spec
131
C source files
1093
C fns defined
891
Fns ported
81.5%
Coverage
145
src .rs files
88.9k
Source lines

## ~PORTING METHODOLOGY

The C source is the spec. Ports are faithful; the original C is translated function-for-function. The gate keeps the port from drifting into a reimplementation.

Layer | Implementation
--- | ---
Spec | htop 3.5.1 at `~/forkedRepos/htop` — 131 `.c` files, platform-split (darwin / linux / freebsd / netbsd / openbsd / dragonflybsd / solaris / pcp)
Port tree | `src/ported/<file>.rs`, one Rust module per C file; every `fn` carries a `/// Port of` citation naming its `<File>.c:<line>` origin
Port-purity gate | `build.rs` (std-only) scans `src/ported/` on every `cargo build` / `test` / `check`; a free `fn` whose name is absent from `tests/data/htop_c_fn_names.txt` and the allowlist fails the build — cannot be bypassed by `cargo test --test X`
C-name snapshot | `tests/data/htop_c_fn_names.txt`, regenerated by `tests/data/extract_c_fn_names.sh` (`HTOP_C_SOURCE=~/forkedRepos/htop`) after pulling upstream htop
Allowlist | `tests/data/fake_fn_allowlist.txt` — genuine Rust-only architectural helpers only, each justified inline; currently empty
Port report | `scripts/gen_port_report.py` → port_report.html, per-file + overall coverage derived from source at run time (nothing hardcoded)

## &PORTED SUBSYSTEMS

121 of the 131 C files are started (81.5% of functions). The authoritative per-file, per-function breakdown is the port report, generated from source; this table groups the port by subsystem.

Subsystem | Ported layer
--- | ---
Core model | `Process` / `ProcessTable` / `Table` / `Row` / `Machine` / `Object` / `Settings` — the process model, table build, and settings
Containers & utils | `Vector`, `Hashtable`, `RichString`, `XUtils` — sort/search, prime-table, attributed strings, string/math helpers
Meters | `Meter` plus CPU / Memory / Swap / Load / Battery / Network / DiskIO / GPU / ZFS / DateTime / Uptime / Tasks / dynamic meters
UI panels | `Panel` / `ScreenManager` / `MainPanel` / `FunctionBar` / `Header` and the setup / columns / colors / display-options / affinity / signals panels
Screens & input | `Action` key dispatch, `IncSet`, `LineEditor`, and the trace / env / info / open-files / process-locks screens
ncurses shim | `CRT` — the crossterm-backed terminal layer (colors, mouse, key decode)
Platforms | darwin / linux / freebsd / netbsd / openbsd / dragonflybsd / solaris machine & process-table backends

The C allocation / memory machinery (the `xMalloc` family, the raw `Object**` dynamic array, the open-addressing bucket table), the null-terminated-string helpers, and the varargs formatters have no faithful safe-Rust analog (Rust's `Vec` / `HashMap` / `String` own allocation, bounds, probing, and lifetimes) and are intentionally not ported. The remaining 31 stubs and un-started files are tracked in the port report.

## +HTOPRS-ORIGINAL EXTENSIONS

Beyond the faithful port, an `src/extensions/` layer (18 modules, exempt from the port-purity gate) adds capabilities htop lacks. These are htoprs-original, not translations of htop C.

Area | Capability
--- | ---
Theming | 31 named color schemes with a live chooser / editor overlay (`c` / `C`), recoloring the ncurses UI in 256-color; persisted to `~/.config/htoprs/prefs.json`
Monitoring | Per-PID CPU/mem history rings, debounced threshold alerts (`A`), a fuzzy process finder (`f`), regex filters (`r`), snapshot diffs (`d`), and JSON/CSV export (`o`)
Braille graphs | A full braille CPU history graph (`G`) and an inline per-process CPU graph whose height scales with load (`v`)
Chrome | A themed help overlay (`h`/`?`), a border toggle (`B`), and a bar-fill-glyph cycler (`b`)

## $CI GATES

Gate | Command
--- | ---
port-purity | `cargo build` (build.rs rejects any non-htop `fn` under `src/ported/`)
test | `cargo test` — hand-crafted unit tests pin the C edge behavior
fmt | `cargo fmt --all --check`

## #PROJECT METADATA

Item | Value
--- | ---
Version | 0.5.0
License | GPL-2.0-or-later (matching htop)
Spec | htop 3.5.1 — github.com/htop-dev/htop
Precedent | zshrs — the faithful-port + port-purity-gate pattern
Author | MenkeTechnologies
Repository | github.com/MenkeTechnologies/htoprs
Meta umbrella | MenkeTechnologiesMeta