powerliners — Engineering Report

>_EXECUTIVE SUMMARY

powerliners is a structurally complete (134/137 upstream py files at DONE tier) Rust port of Python's powerline-status. The target is a single static binary that drops into the same hook points (tmux statusline, zsh PS1, vim statusline, ipython prompt) with sub-millisecond render — replacing the ~100 ms python-interpreter startup tax that compounds across every render in interactive shells.

~ SCALE & POSITION

Metric	Value	Notes
Rust LOC (src/ported)	~62,168	137-file 1:1 mirror of upstream powerline/
Upstream py fn allowlist	631	`docs/powerline_py_functions.txt` (regen via `scripts/regen_py_functions.sh`)
Audit tests	2	`allowlist_files_are_well_formed` + `every_ported_fn_name_exists_in_python_allowlist`
Lib tests	2,102	port body + parity assertions across the ported surface
Parity tests	219	byte/value identical between Rust port and live upstream Python interpreter
Port bugs fixed	11	surfaced by the parity harness — see git log for the full list
Tier progress	134 / 137 DONE	3 NEAR holdouts are class-only Python sources at classifier ceiling
Target render budget	< 1 ms	vs ~100 ms upstream py-startup
Runtime deps	0	single static binary; no python, no glibc-only features
Current tag	`v0.2.11`	function-level port complete; orchestrator integration in progress

# SUBSYSTEM BREAKDOWN

Subsystem	Module	Role
Path utilities	`src/ported/lib/path.rs`	cross-platform os.path equivalents
Bindings — ipython	`src/ported/bindings/ipython/`	3 version flavours: pre_0_11, since_5, since_7
Bindings — config	`src/ported/bindings/config.rs`	shared config loader
Daemon lifecycle	`src/ported/scripts/powerline_daemon.rs` + `src/bin/powerline-daemon.rs`	UNIX socket bind + daemonize + pidfile lock + accept loop
Parity harness	`tests/parity_against_upstream.rs`	368 tests piping the same input through upstream Python and Rust
Audit harness	`tests/ported_fn_names_match_py.rs`	enforces fn name parity with upstream py
Allowlist	`docs/powerline_py_functions.txt`	631 upstream py fns (regenerable)
Exemptions	`tests/data/fake_fn_allowlist.txt`	maintainer-approved Rust-only fns

@ EXECUTION PIPELINE (target)

argv  ───►  CLI parse  ───►  segment renderer  ───►  encoded statusline
                  │                  │                       │
                  ▼                  ▼                       ▼
            config.json        per-segment fn          tmux/zsh/vim escape sequences
            (powerline-       (host context, time,     (truecolor + box-drawing chars)
            compatible)         git, kube, …)          on stdout

Render path is allocation-light: segments stream into a fixed-capacity output buffer, no intermediate Vec<Segment> when the configuration is static. Hot path uses zero-copy slicing over the config JSON arena.

! PORT DISCIPLINE

The two audit tests are load-bearing: removing or weakening them is treated as audit-tool tampering per the project's global rules (see tests/ported_fn_names_match_py.rs).

Naming. Every fn defined under src/ported/ must have a name that exists in docs/powerline_py_functions.txt, in tests/data/fake_fn_allowlist.txt, or in the small trait-impl exemption set (new, fmt, clone, …).
Layout. Directory structure mirrors upstream — powerline/lib/path.py → src/ported/lib/path.rs, powerline/bindings/ipython/since_7.py → src/ported/bindings/ipython/since_7.rs.
Citation. Each ported fn carries a // py:LINE-LINE comment pointing back to the original Python source range, so reviewers can verify line-by-line.

* TESTS & PARITY

$ cargo test --locked --no-fail-fast
test result: ok. 2014 passed; 0 failed   # lib::tests
test result: ok.    2 passed; 0 failed   # tests/ported_fn_names_match_py.rs (drift gate)
test result: ok.  219 passed; 0 failed   # tests/parity_against_upstream.rs

The parity harness invokes the upstream Python interpreter (via the vendored powerline-status at vendor/powerline/) and compares its return values against the Rust port for the same inputs. 11 real port bugs were surfaced this way and fixed: ThreadedSegment.daemon class-attr override, Spec.did_type gating logic, encoding-locale env-var lookup, _clear_special_values use-after-free (BTreeMap rebalance invalidated saved raw pointers), Spec.ident regex (rejected colon-form identifiers like solarized:term), Spec.context_message child-recursion, Spec.tuple length bounds (lower bound silently dropped), Spec.unknown_msg arg-drop, Spec.unknown_spec dispatch-tuple loss, NON_PRINTABLE_RE regex-class inversion, and Spec.printable/unsigned chained constraints.

~ CRANELIFT JIT (future)

Out of scope for the initial port. powerline-status is render-bound, not compute-bound — Cranelift gives no win until segment computation surface includes user-extensible scripting. Re-evaluate after the static segment pipeline ships and benchmark numbers show where the actual hot loop is.

. NEXT MILESTONES

Glue the Powerline orchestrator chain (Powerline class → Theme → Renderer → segment dispatcher) into the powerline-render binary so a real ~/.config/powerline/themes/... tree produces statusline output.
Wire the daemon render path through the orchestrator so powerline-daemon serves segment output over its UNIX socket instead of the current placeholder string.
End-to-end byte-identical comparison: feed powerline/config/themes/tmux/default.json through both the Rust pipeline and python -m powerline.commands.main, assert byte-identical output.
First benchmark: render the user's daily-driver tmux config 10,000× and report wall-clock vs upstream py.
Grow the parity harness past the current 368 tests — at minimum one fixture per Python source file with function bodies.