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 is at an early stage — `XUtils.c`'s string/math utility layer is the first file landed.

v0.1.0
Version
3.5.1
htop spec
131
C source files
1093
C fns defined
16
Fns ported
1.46%
Coverage
7
src .rs files
797
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 FILES

The pure-logic layers are ported first. The live per-function breakdown and coverage are in the port report, derived from source at generation time; this table is the file-level summary.

C file | Ported layer
--- | ---
`XUtils.c` | string / math utilities — `String_cat` / `_trim` / `_split` / `_splitFirst` / `_contains_i`, `compareRealNumbers`, `sumPositiveValues`, `countDigits`, `countTrailingZeros`
`Vector.c` | container sort / search core — `swap`, `partition`, `quickSort`, `insertionSort`, `Vector_indexOf` (generics over a slice with a C-`int` comparator)
`Hashtable.c` | prime-table math — `nextPrime`
`Meter.c` | value formatting — `Meter_humanUnit`

The C allocation / memory machinery (the `xMalloc` family and `String_freeArray`; the `Object**` dynamic array — `Vector_new` / `_insert` / `_resizeIfNecessary` …; the open-addressing bucket table — `Hashtable_new` / `_put` / `_get` …), 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.

## $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.1.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