// LSOFRS — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

lsofrs is a single-binary Rust implementation of lsof. Three platform backends (src/darwin.rs via libproc FFI, src/linux.rs via /proc, src/freebsd.rs via sysctl + procfs) feed a shared Vec<Process> through a composable filter pipeline (src/filter.rs) into one of fourteen output / live-monitor modes. Per-PID FD enumeration runs on rayon's work-stealing pool; every TTY mode shares a TuiMode trait (src/tui_app.rs) for common keybindings, alternate-screen entry/exit, and atomic frame rendering. 23,441 production Rust lines + 8,560 test lines + 1,662 #[test] functions. hyperfine wall-clock: 14.2 ms for the default invocation vs 169.8 ms for lsof 4.91 (~12× speedup), 21× on terse PID output.

~BENCHMARK POSITION

hyperfine wall-clock (10 runs, 3 warmup, ~470 processes / ~5000 open files on macOS). Reproducible from README § PERFORMANCE. The rayon-parallel per-PID enumeration + zero-copy FFI + OnceCell-cached getpwuid together push the steady-state cost below 15 ms.

#SUBSYSTEM BREAKDOWN

Source partitioned by role. TUI & theming dominate at 31.3% of production Rust — tui_tabs.rs alone is 5,308 lines for the unified 7-tab dashboard (mouse, tooltips, theme chooser + editor). Selection / filter is the second-biggest subsystem (2,659 lines) because every selector composes with every other under OR / AND mode with regex, range, and negation grammar.

$TOP 20 FILES BY SIZE

The 20 largest files account for 84.2% of the codebase (Rust under src/ + tests/). tui_tabs.rs is by far the largest single file — the entire 7-tab dashboard, mouse handling, tooltips, and theme picker live there. The four largest test modules (json_and_csv_contracts, integration, cli_combinations, dispatch_contracts) cover 6,602 lines — every flag combination, every JSON shape, every CSV escape rule.

@EXECUTION PIPELINE

One invocation flows through three stages: gather (platform-specific FFI, parallel per-PID), filter (composable selectors, AND/OR mode), output (one of: columnar TTY, columnar plain, JSON, CSV, field, or live TUI). The shared Process / OpenFile shape from src/types.rs means every backend feeds every output mode without intermediate marshaling.

  argv  ──▶  cli.rs (clap derive, 38 args)
                  │
                  ▼
         ┌────────────────┐
         │   main.rs      │  mode dispatch:
         │   (282 lines)  │   tui / top / summary -r / monitor /
         │                │   watch / follow / leak-detect /
         │                │   tree / ports / stale / pipe-chain /
         │                │   net-map / csv / json / field / list
         └────────┬───────┘
                  │
       ┌──────────┴──────────┐
       │                     │
       ▼                     ▼
 #[cfg(target_os = …)]  filter.rs  (2,659 lines)
 ┌───────────┐           - PID / PGID / USER / CMD
 │ darwin.rs │           - FD range / exclusion
 │ (1,253)   │           - network spec (4|6|TCP|UDP|:port)
 │ libproc   │           - path canonicalization
 │ FFI       │           - AND mode (-a) / OR mode (default)
 │ repr(C)   │           - regex via /…/
 └─────┬─────┘
       │
 ┌───────────┐
 │ linux.rs  │
 │ (820)     │
 │ /proc fs  │     ┌──────────────────────┐
 │ rayon     │ ──▶ │  Vec<Process>        │
 │ per-PID   │     │  (types.rs, 867 ln)  │
 └─────┬─────┘     │   Process            │
       │           │   ├─ OpenFile        │
 ┌───────────┐     │   │   ├─ FdType      │
 │freebsd.rs │     │   │   └─ SocketInfo  │
 │ (835)     │     │   └─ command/uid/…   │
 │sysctl+proc│     └──────────┬───────────┘
 └───────────┘                │
                              ▼
                ┌─────────────────────────────┐
                │   output dispatch           │
                ├─────────────────────────────┤
                │ output.rs   - columnar/TTY  │
                │ json.rs     - serde JSON    │
                │ csv_out.rs  - RFC 4180      │
                │ tui_app.rs  - TuiMode trait │
                │   └─ tui_tabs, top,         │
                │      summary, monitor,      │
                │      follow, watch, leak    │
                └─────────────────────────────┘

&TYPE SYSTEM

Eleven public struct / enum definitions in src/types.rs (867 lines) carry every fact between the gather, filter, and output layers. All of them #[derive(Serialize, Deserialize)] so the JSON contract is one derive macro — no hand-rolled escaping, no schema drift.

%MODES MATRIX

Fifteen distinct entry points dispatched from main.rs based on which flag is set. Single-shot modes print and exit; live modes share tui_app.rs's TuiMode trait for common keybindings and atomic frame rendering.

!DEPENDENCY AUDIT

Thirteen direct dependencies, all foundational crates from the durable-by-design tier (libc, nix, serde, clap, regex, rayon, chrono) with one TUI layer (ratatui + crossterm). Picked for "will this still build cleanly in 2035" — no curl-pipe-bash installers, no flaky build scripts, no nightly-only features.

?TEST SURFACE

1,662 #[test] functions across 10 integration modules and 20 inline #[cfg(test)] blocks. The integration suite is contract-heavy: every JSON field, every CSV escape, every CLI flag combination is pinned so refactors can't silently shift output shape.

*SHIPPING ARTIFACTS

=INVARIANTS

Constraints the codebase enforces or relies on. Listed here so future changes know which lines are load-bearing.

>>WHERE NEXT

• Docs index — quickstart, mode catalog, selection grammar, JSON shape, interactive controls.
• README — install, every flag with examples, full benchmark table, screenshots.
• docs.rs/lsofrs — rustdoc for the library crate.
• lsofrs.1 — full man page (also man lsofrs after install).
• Issues — bug reports, feature requests, perf regressions.
• crates.io/crates/lsofrs — releases, downloads, version history.