Documentation

jinx reads Nix and writes TypeScript that evaluates to the same thing. These pages are the design and the evidence, in reading order. The source is in the repository under docs/.

Usage: jinx eval compiles the files an evaluation reaches into a cache under ~/.cache/jinx and runs them. There is no search path: nixpkgs is named by its path. The commands:
Why: Nix evaluates nixpkgs with an interpreter, and an interpreter gives you a value. jinx gives you a program, and the tools built for TypeScript work on it.
Design: jinx compiles Nix to TypeScript. This document is the decisions that make the derivations byte-identical, and why. semantics.md is the value-by-value mapping; verification.md is how the claims are checked.
Semantics: The mapping from Nix to the emitted TypeScript, construct by construct, with the runtime helper each one calls. nix is the runtime namespace (src/runtime/index.ts). S(e) is the emission of e in a strict position (a value), L(e) in a lazy position (a value or a thunk).
Verification: jinx claims to compute the same derivations as Nix. This document is how that is tested, at four levels, from a single builtin to all of nixpkgs. Each level runs offline from recorded expectations in nix flake check, and against a live Nix when asked.
Performance: How fast jinx evaluates nixpkgs against Nix on the same machine and the same nixpkgs. The numbers are one run of tools/bench.ts; the benchmark page draws every run. The design behind the numbers is in design.md.
Constraints: What jinx does not do, and the deviations it knows about. The ones that matter for nixpkgs come first.
Comparisons: Where jinx sits among the other implementations of the Nix language.
The compiled nixpkgs: fzakaria/jinx-nixpkgs is nixpkgs compiled to TypeScript, one commit per tracked nixpkgs revision. Every .nix file is a .ts module in the same place, with a source map beside it pointing back at the Nix, and the runtime the modules import is vendored under .jinx/runtime, so the tree stands alone.