jscd

Reverse bytenode-compiled .jsc files back to JavaScript. Static parsing only: one pure-Rust binary — no patched V8, no Node runtime, no network.

Supports Node 8.0.0 → 26.10.0 (510 releases / 36 V8 minors); ≈ 25k .jsc files pass the tests with 0 failures (31 Node lines × 41 fixtures, compiled with bytenode 1.7.0's flags); two optimization layers (register folding → swc copy propagation) make the decompiled source readable.

English · 中文

Contents: Highlights · Quick start · Install · Usage · CLI reference · Supported versions · How it works · Verification · Repository layout · Limitations · Contributing

Highlights

• Coverage — every Node release from 8.0.0 → 26.10.0 (510 releases / 36 V8 minors) is identified; a V8 outside the tables is a clear error, not a guess.
• Runnable output — --runtime adds the __runtime stubs so the result runs under node; --verify puts it through node --check.
• Readable output — two optimization layers fold bytecode register shuffling back into expressions (register folding → swc copy propagation); JSCD_NO_OPT=1 shows the raw form.
• Names recovered — scope slots are named, builtins resolved through a read-only-heap name table; never an identifier that throws ReferenceError.
• One dependency-free binary — pure Rust: no Node, no network, no patched V8; the Linux build is a 2.8 MB static binary (UPX).
• Reproducible verification — 31 Node lines × 41 fixtures compared case by case, plus corpus sweeps; every number rerunnable (see Verification).

Quick start

$ cat hello.js
function greet(name) {
  return "hello " + name;
}
console.log(greet("world"));

$ npm i -g bytenode && bytenode -c hello.js      # Node 20.20.2 in this transcript
$ xxd -l 48 hello.jsc
00000000: cc05 dec0 0bc2 e400 9200 0000 e521 2eaa  .............!..
00000010: f002 0000 0000 0000 011c 5401 2006 a860  ..........T. ..`
00000020: 0000 0000 0600 0000 010c 4c60 0000 0000  ..........L`....

$ jscd hello.jsc
console.log(greet("world"));
function greet(a0) {
    return "hello " + a0;
}

$ jscd hello.jsc --runtime > hello.out.js && node hello.out.js
hello world

The first bytes are the code-cache magic in little-endian (cc 05 de c0 = 0xc0de05cc); jscd info hello.jsc decodes the whole header (sample in Usage).

The output above is what comes out after both optimization layers. JSCD_NO_OPT=1 jscd hello.jsc shows the raw translation instead — V8's register shuffling, one instruction at a time.

On Node 22+ (V8 12.4+) some built-in property names live in the read-only heap. For the 29 V8 minors covered by the behavior matrix jscd ships a name table (tables/ro_map_*) and resolves them automatically — on macOS, where those tables were extracted: read-only-heap indices are platform-specific, so on other systems build your own with jscd ro-map and pass --ro-map (JSCD_NO_RO_MAP=1 turns the embedded table off). Without a table such names show as <ro0_…> placeholders — never as the wrong name.

Install

macOS / Linux — Homebrew

brew install ejfkdev/tap/jscd

Windows — Scoop

scoop bucket add ejfkdev https://github.com/ejfkdev/scoop-bucket
scoop install jscd

Straight from the manifest URL, without adding the bucket first:

scoop install https://raw.githubusercontent.com/ejfkdev/scoop-bucket/main/bucket/jscd.json

scoop install ejfkdev/scoop-bucket/jscd does not work: Scoop resolves bucket/app against buckets you have already added, not against an owner/repo path.

Prebuilt binaries — every tagged release ships bare, ready-to-run executables (Linux / macOS / Windows × x64 / arm64; Linux amd64 is a static musl build, Linux and Windows are UPX-compressed):

Grab one straight from the release page (no archive, no installer — the file is the executable):

curl -fLO https://github.com/ejfkdev/jscd/releases/download/v0.1.0/jscd-v0.1.0-linux-amd64
chmod +x jscd-v0.1.0-linux-amd64
./jscd-v0.1.0-linux-amd64 --version

cargo (any platform with Rust 1.96+)

cargo install jscd        # build from crates.io
cargo binstall jscd       # or fetch the release binary instead of compiling (cargo-binstall)

From source

cargo install --git https://github.com/ejfkdev/jscd     # latest main
git clone https://github.com/ejfkdev/jscd && cd jscd
cargo build --release        # -> target/release/jscd
cargo install --path .       # ...or install that build into ~/.cargo/bin

Requires Rust 1.96+ (swc, the JS optimizer, needs a recent rustc). No system dependencies.

Releasing (maintainers)

scripts/release.sh vX.Y.Z runs the release gates (cargo test --release, clippy --all-targets -- -D warnings, and the end-to-end smoke scripts/ci_smoke.sh — fixtures compiled to real .jsc, decompiled, syntax-gated and run-compared), then pushes an annotated tag whose message becomes the GitHub Release description. The tag triggers .github/workflows/release.yml, which rebuilds the six bare binaries listed above. Then cargo publish to crates.io (release.sh keeps the tag and the Cargo.toml version in sync), and python3 scripts/update_readme_help.py to refresh the CLI help below; the Homebrew tap and the Scoop bucket pick the new release up on their daily auto-update run.

Usage

jscd app.jsc                     # decompile one file to stdout
jscd app.jsc app.js              # ...to a file
jscd dist/                       # every .jsc under dist/ → dist-out/ (tree mirrored)
jscd dist/ out/                  # ...into out/ instead
jscd info app.jsc                # header fields, detected Node/V8 version
jscd disasm --filter main app.jsc
jscd ro-map probe.jsc > m.json   # build a read-only-heap name table
jscd --help                      # bilingual help (-h, `help`, `help <SUBCOMMAND>`)

• Input is one .jsc file, or a directory scanned recursively for *.jsc; output defaults to stdout for a file and to <INPUT>-out/ (tree mirrored) for a directory — -o / the OUTPUT argument writes elsewhere, - means stdout.
• A .jsc from an unsupported V8 is rejected with the detected version and the supported range in the message (jscd info prints supported: yes|no) — never a silent, runtime-only file.
• Read-only-heap names (Node 22+) resolve automatically where an embedded table applies (macOS — RO indices are platform-specific); elsewhere build one with jscd ro-map and pass --ro-map (JSCD_NO_RO_MAP=1 disables the embedded table). A mismatched table is ignored: you get <ro0_…> placeholders, never a wrong name.
• The interface language follows JSCD_LANG (then LC_ALL / LC_MESSAGES / LANGUAGE / LANG / LC_CTYPE): zh* is Chinese, anything else English; JSCD_LANG=zh|en forces one.