// ZSHRS — C-TO-RUST PORT COVERAGE REPORT

>_EXECUTIVE SUMMARY

Large-scale C-to-Rust port of upstream zsh: strict-port code under src/ported/ plus non-port extensions. The core file table below is regenerated from the same indexer as port_report.html (regex C top-level defs + Rust fn names + port-doc mining). Those counts are a mechanical index, not proof that every path is behavior-complete.

Codebase split (NEW): the runtime crate now physically isolates ported code from non-port code so drift is mechanically detectable. src/ported/ is the strict-port directory — every .rs mirrors a real src/zsh/Src/<x>.c file, every top-level fn carries a /// Port of <cname>() from Src/<file>.c:NNNN doc-comment, and the file set is FROZEN (no new files). src/extensions/ is the non-port directory — features zsh C does not have (AOT, daemon coordination, plugin/script/autoload caches, fish-style autosuggest/abbrev/highlight, persistent worker pools, ZWC byte-code helpers). src/recorder/ is feature-gated; deleted by rustc in the default build. Both invariants are enforced by tests/port_purity.rs — a regression of either rule fails CI.

Scope note: this report covers the C-to-Rust port (i.e. src/ported/ only) — what was translated from upstream zsh. It does not cover the new Rust infrastructure layered on top (zshrs-daemon singleton, zshrs-recorder AOP intercept, IPC + HTTP + OpenAPI surface, canonical-state rkyv shards, the z* builtin family, session-persistent supervised jobs with bidirectional ptmx attach, the parser surface in src/ported/parse.rs). That work has no C ancestor and is reported separately in daemon-report.html. See “BEYOND THE C PORT” section below for the cross-link.

#FILE-BY-FILE COVERAGE

Per-file columns: C Fns = symbols whose primary C definition is that file (unique name, heuristic indexer). Same-name Rust fn = a Rust definition with the identical identifier. Other rows = the remainder (doc-only pointers, different Rust names, or not yet indexed). Port-index % = ported / total from gen_port_report.py (ported = any Rust hit or port-doc mention). Rust targets: src/ported/<stem>.rs.

&RENAMING PATTERNS

C uses free functions with global state. Rust uses struct methods, enum variants, and pattern matching. Every “renamed” C function maps to a Rust equivalent under an idiomatic name. This section explains the mapping patterns.

$KEY FEATURES PORTED

@PER-SYMBOL PORT INDEX

Hand-maintained per-function tables previously claimed a fixed “859” row total and drifted (wrong Rust paths, inflated coverage). Those rows are removed. The port_report.html file produced by python3 scripts/gen_port_report.py lists every C symbol the indexer extracts from src/zsh/Src/**/*.c (heuristic: top-level ident( with a following {) together with Rust placement and port-doc pointers — regenerate after upstream or port changes.

The core file table above (between PORT_REPORT:CORETABLE markers) is rewritten by the same script from live tree counts; it is not manually curated.

!TEST RESULTS

Pass/fail counts are intentionally not pinned in this HTML snapshot (they drift with feature flags and cargo version). The static surface is the #[test] hook total in the engineering overview below. For a local matrix run cargo test with the same features you ship; when triaging ordering-sensitive cases, --test-threads=1 remains the tie-breaker.

~ARCHITECTURE: WHY RUST IS DIFFERENT

%ENGINEERING OVERVIEW

Workspace-wide cargo workspace layout (zshrs root crate — compsys folded in — plus zshrs-daemon, znative, and vendored crates). Size figures are not typed here; regenerate them with git ls-files '*.rs' | xargs wc -l when needed.

ΔMAY 2026 — RECENT PORT WORK

Three themes closed out across May 2026: (1) every // Deferred / // FAKE / // stub marker in builtin.rs turned into a real C-faithful body, (2) the try_with_executor dispatch path — a Rust-only abstraction that bypassed paramtab — was removed from src/ported/ in May (40 → 0 call sites; later work reintroduced calls, see below), and (3) all 30 module files (clone/cap/example/datetime/socket/tcp/stat/zftp/zprof/zselect/watch/zpty/termcap/terminfo/attr/system/zutil/ksh93/db_gdbm/pcre/param_private/mathfunc/langinfo/hlgroup/mapfile/parameter/nearcolor/random/regex/files) were migrated from per-module featuresarray/handlefeatures/getfeatureenables/setfeatureenables stub copies to the canonical crate::ported::module::* impls — 4 stubs × 30 modules = 120 duplicate fake fns deleted, replaced with slice-based module::Features { bn_list, cd_list, mf_list, pd_list } arrays populated with the real BUILTIN/CONDDEF/MATHFUNC/PARAMDEF entries.

Other major de-faking in May: fake structs in hashtable.rs deleted (CmdName / Alias / Reswd / DirCache / SuffixAliasTable / ReswdToken / ShFunc impl block — all replaced with canonical lowercase C-named structs from zsh_h.rs), jobs.rs deleted (JobEntry / BgStatus / PipeStats / CommandTimer / JobPointers fake aggregates; JobState/JobInfo/JobTable moved out to exec_jobs.rs), input.rs deleted (StringInput convenience wrapper, InputBuffer aggregate, INP_* drift constants), glob.rs deleted (GlobOptions / GlobSort / SortOrder / SortSpec / TimeUnit / SizeUnit / RangeOp / impl GlobMatch), cond.rs deleted (CondType / CondResult / CondEval fake enums), module.rs deleted (Wrapper struct + addwrapper/deletewrapper), options.rs deleted (ShellOption enum, with opt_state_get("name") globally swapped to isset(OPT_CONST)).

try_with_executor in src/ported/: the May 2026 migration took it from 40 call sites to 0; live calls have since returned in exec.rs, builtin.rs and subst.rs (list them with grep -rn 'try_with_executor(' src/ported | grep -v //).

*MODULE BREAKDOWN BY SUBSYSTEM

Every tracked .rs file under src/ported/ assigned to exactly one subsystem; lines from git ls-files 'src/ported/*.rs' | xargs wc -l (106 files), 2026-10-18.

+33 LOADABLE MODULE PORTS

Each C module from src/zsh/Src/Modules/ has a corresponding strict-port Rust implementation in src/ported/modules/. Module file set is included in the file freeze on src/ported/; every module now routes its features_ / enables_ / cleanup_ hooks through the canonical module::featuresarray / handlefeatures / setfeatureenables impls instead of per-module Rust-only stub copies.

^ZLE LINE EDITOR — 28 FILES, 125,185 LINES

The Zsh Line Editor (ZLE) is a complete terminal-based input system with vi and emacs keybinding modes, programmable widgets, and inline completion. Ported from src/zsh/Src/Zle/*.c. Files mirror the C source 1:1 with the canonical zsh prefix (zle_* / comp* / termquery / deltochar).

;PORTED SHELL BUILTINS

The ported builtin table is BUILTINS in src/ported/builtin.rs; each BUILTIN(...) row names its bin_* handler, defined in src/ported/builtin.rs or in the port file that owns it (src/ported/modules/*.rs, src/ported/zle/*.rs, jobs.rs, options.rs, builtins/rlimits.rs, …). The table holds BUILTIN( rows (fg, kill and suspend are each registered twice) and BIN_PREFIX( precommand modifiers; every distinct BUILTIN name is listed below. compat_builtin_names() (src/extensions/ext_builtins.rs), which feeds the reference’s Compat Builtin Index and zbanner, dedups the table. The zshrs extension builtins (EXT_BUILTIN_NAMES: coreutils, parallel primitives, compgen/complete, …) are a separate table and are not listed here.

&DEPENDENCY ARCHITECTURE

Line counts are wc -l on the named files under src/ported/ (directories: sum of their tracked .rs files), 2026-10-18.

               ┌─────────────────────────────────────┐
               │          exec.rs (15,029)           │
               │         builtin.rs (25,612)         │
               └──────────────────┬──────────────────┘
                                  │
      ┌───────────────────────────┼───────────────────────────┐
┌─────▼─────┐               ┌─────▼─────┐               ┌─────▼─────┐
│ parse.rs  │               │  lex.rs   │               │ subst.rs  │
│ (12,808)  │               │  (7,739)  │               │ (34,354)  │
└─────┬─────┘               └───────────┘               └─────┬─────┘
      │                                                       │
      ├─────────────┬─────────────┬─────────────┬─────────────┼─────────────┐
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│  params   │ │  pattern  │ │   glob    │ │   hist    │ │   math    │ │   text    │
│ (23,620)  │ │ (11,279)  │ │  (9,934)  │ │  (9,186)  │ │  (7,752)  │ │  (2,455)  │
└─────┬─────┘ └───────────┘ └───────────┘ └─────┬─────┘ └───────────┘ └───────────┘
      │                                         │
┌─────▼─────┐ ┌───────────┐ ┌───────────┐ ┌─────▼─────┐ ┌───────────┐ ┌───────────┐
│   utils   │ │   jobs    │ │  signals  │ │  prompt   │ │   init    │ │  options  │
│ (17,967)  │ │  (7,803)  │ │  (3,871)  │ │  (7,230)  │ │  (3,614)  │ │  (3,630)  │
└───────────┘ └─────┬─────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘
                    │
      ┌─────────────┼─────────────┬─────────────┐
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│   zle/    │ │   cond    │ │   loop    │ │ modules/  │
│ (125,185) │ │  (2,220)  │ │  (1,300)  │ │ (69,562)  │
└───────────┘ └───────────┘ └───────────┘ └───────────┘

◆COMPSYS — ZSH COMPLETION SYSTEM IN RUST

zsh’s compsys — the programmable completion system — inside the runtime crate under src/compsys/ (the former standalone crate was folded in). Runtime files plus engine ports under src/compsys/ported/, which sit beside the upstream Completion/ files copied verbatim.

// 250 ENGINE PORTS BY UPSTREAM DIRECTORY

⬢FUSEVM + LEX / PARSE (src/ported/)

Runtime bytecode targets the crates.io fusevm crate (pinned in workspace Cargo.toml). Lexing and parsing live in src/ported/lex.rs and src/ported/parse.rs in the runtime crate (the standalone parse package was absorbed back). Stryke / strykelang is a separate repository — it is not part of this workspace; the former Perl-interpreter block here was erroneous pasted content.

// LEX + PARSER (IN-CRATE PORTS)

// EXECUTION PIPELINE (ZSHRS)

  Source / REPL input (zsh script)
       │
       ▼
  ┌─────────────────┐     ┌──────────────────┐
  │  Lexer          │────▶│  Parser          │
  │  (lex.rs)       │     │  (parse.rs)      │
  │  token stream   │     │  AST / commands  │
  └────────┬────────┘     └────────┬─────────┘
           │                       │
           └───────────┬───────────┘
                       ▼
              ┌────────────────────┐
              │ compile_zsh (+AOT) │  ──▶  fusevm bytecode (workspace crate)
              │ extensions/        │
              └─────────┬──────────┘
                        ▼
              ┌────────────────────┐
              │ ShellExecutor / VM │  ──▶  builtins, jobs, redirects, zle
              └────────────────────┘

●BEYOND THE C PORT — RUNTIME INFRASTRUCTURE

The C-to-Rust port covered above lives under src/ported/ against upstream src/zsh/Src/**/*.c. The numbers below count what zshrs adds — new Rust code with no C ancestor. This is the layer that takes zshrs from “zsh in Rust” to “the first JIT-compiled Unix shell with a session-persistent daemon, AOP-intercept recorder, and bidirectional ptmx-attach job supervisor.” Non-port runtime code lives in src/extensions/ — mechanically isolated from src/ported/ by tests/port_purity.rs.

Architectural moves with no zsh equivalent: the 90/10 daemon/shell work split (singleton daemon owns every mutation; thin shell clients are stateless and forkable); the recorder-owns-rebuild stance (no in-daemon walker; zshrs-recorder is the sole producer of recorder-managed canonical subsystems); the single ~/.zshrs/ directory rule (every config + log + sqlite + rkyv shard + socket under one root, configurable via $ZSHRS_HOME); the z* builtin family (zcache / zls / zsend / znotify / zsubscribe / zjob / zsync / zask / zlock / zpublish / zwhere / zd); session-persistent supervised jobs with bidirectional ptmx attach (replaces nohup + screen + pueue + disown); the auto-derived OpenAPI 3.1 surface at GET /openapi from the daemon op registry; the flat zsh-extended-history text file + sibling FTS5 sqlite index; zsh grammar introspection to stdout (lexer token stream, Eprog wordcode layout, parser AST S-expression) via zshrs --dump-* and zshrs_dump (dumptokens, dumpwordcode) in formats byte-diffable against parity harnesses — not shipped as a trio by stock zsh. Op-by-op detail in daemon-report.html.

≡GRAND TOTAL — FULL WORKSPACE

Four Rust packages in one Cargo workspace (zshrs + zshrs-daemon + znative + zshrs-runtime, the 16-line crate that emits the zsh staticlib for AOT linking; compsys was folded into zshrs). Size figures are not typed here; regenerate them with git ls-files '*.rs' | xargs wc -l.