jscd

Reverse bytenode-compiled .jsc files back to JavaScript.

A .jsc is a V8 code cache (v8::ScriptCompiler::CreateCodeCache). jscd parses it statically: pure Rust, one binary, no patched V8, no Node runtime, no network.

English (this file) · 中文 · Version-by-version notes (Chinese)

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

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

Prebuilt binaries for Linux, macOS and Windows (x64 and arm64) are attached to each tagged release. From source:

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

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

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.

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 to a file or directory, - means stdout.
• A .jsc from a V8 outside the table range is rejected with the detected version and the supported range in the message, rather than silently emitting a runtime-only file; jscd info carries a supported: yes|no line for the same reason.
• Read-only-heap names (Node 22+) resolve automatically for the builds shipped in tables/ro_map_* — on macOS, the platform those tables were extracted on (RO indices depend on the platform, so an embedded table is applied only where it can be trusted). Elsewhere build one with jscd ro-map / scripts/build_ro_map.sh and pass --ro-map; JSCD_NO_RO_MAP=1 disables the embedded table. A table that does not match is ignored — you get <ro0_…> placeholders rather than wrong names.
• The interface language follows JSCD_LANG (→ LC_ALL → LC_MESSAGES → LANGUAGE → LANG → LC_CTYPE): zh* is Chinese, anything else English. JSCD_LANG=zh|en forces one.

By default the output is just the reconstructed code — no runtime preamble and no comments (the AST layer strips even the structural markers; JSCD_NO_OPT=1 keeps them). --runtime prepends the __runtime proxy (minimal stubs for the V8 builtins the bytecode calls), the file-level declarations for flattened context variables, and the name-alias block, so the file runs as-is with node.

$ jscd info hello.jsc
file:          hello.jsc
size:          776 bytes (raw) / 776 bytes (decompressed)
brotli:        no
magic:         0xc0de05cc (external refs: 0x5cc)
version_hash:  0x00e4c20b
source_hash:   0x00000092 (source length: 146 bytes, module: no)
flag_hash:     0xaa2e21e5
ro_checksum:   (absent)
payload:       752 bytes at offset 24
checksum:      0x00000000
node:          v20.20.2
v8:            11.3.244.8 (exact)
supported:     yes

Two optimization layers

JSCD_NO_OPT=1 disables both, for diffing against the raw translation.

1. Text layer (src/opt.rs): folds away bytecode register shuffling — single-use values are inlined into their use, stores overwritten before any read are dropped, unused register declarations and pure bookkeeping such as DeclareGlobals are removed, let r0; … r0 = E; is lifted into a declarator initializer, the CallProperty-rendering leftover rX = A.B; is dropped (the call already reads the property at the call site, so keeping it would run a getter twice), and expressions are rebuilt: V8 hoists the receiver and every argument into registers, and a dedicated pass folds those single-use loads back into the call, in JavaScript evaluation order (receiver → property → arguments), so nothing is reordered. It refuses to cross blocks, loop headers, braceless control bodies, or any later use of the value (including the self-referencing write r2 = new r2(a0)).

2. AST layer (src/opt_js.rs): the text is handed to swc — the Rust port of terser — for copy propagation, unused-variable elimination and constant folding:

   let r0, r1, r2, r3;        // as decompiled            // after both layers
   r0 = greet;                console.log(greet("world"));
   r2 = console;       →      function greet(a0) {
   r1 = r2.log;                 return "hello " + a0;
   r3 = r0("world");          }
   r2.log(r3);
   

   The pipeline is calibrated: paren_remover → resolver → optimize → hygiene → fixer (skipping paren_remover miscompiles), the snippet is wrapped in a function first (swc only propagates copies inside function scope, and the payload is a Module.wrap function body at runtime anyway) and the wrapper is stripped afterwards; no renaming, no statement merging, no arrow conversion, names and parameters kept. Unparseable or suspicious output → the text-layer result is kept instead.

Supported versions

Version tables are generated from Node sources by scripts/codegen.py and embedded at build time. Selection is keyed on the V8 version hash; every Node release from 8.0.0 on is listed in tables/manifest.json (510 entries), and one table covers each V8 minor — identical tables are stored once.

Every Node release from 8.0.0 through 26.10.0 is identified (510 releases, 90 V8 versions), and 29 of the 36 V8 minors pass the full behavior matrix — 31 Node lines, all green (1,108 pass / 0 fail / 8 skip / 0 known-fail). The remaining 7 minors (5.8, 6.0, 6.1, 6.6, 6.7, 7.0, 7.4) are identified by jscd info but their payload deserialization errors out loudly instead of emitting garbage.

8.17 10.24 12.5 12.9 12.15 12.22 13.14 14.0 14.4 14.5 14.6 14.21 15.14 16.3 16.5 16.8 16.9 16.20 17.1 17.9 18.2 18.20 19.1 19.9 20.20 21.7 22.12 23.11 24.12 25.9 26.10

Generation fetches only the ~30 V8 source files it needs per version, through a blob-filtered partial clone plus an on-disk file cache (workspace/node-src/); no full Node checkout is required:

python3 scripts/codegen.py --all-from 8.0.0 --donors tables/ --per-minor --keep-existing

How it works

What a .jsc holds

It contains no source text, and the header's source_hash field stores the source length, not a hash. Recoverable data:

• header fields: version_hash, flag_hash, payload length, checksum, Brotli or raw payload
• SharedFunctionInfo tree and scope info (parameter, context and stack slots)
• string and literal constant pools, bytecode arrays, source-position and handler tables

decompile emits a syntactically valid pseudo-JS reconstruction. Names that exist only as scope slots are printed as slot names (rN, __ctx.ctxN, _anon_N), never as identifiers that would throw ReferenceError.

Pipeline

1. header — parse SerializedCodeData (24 bytes for V8 ≤ 11, 32 bytes for V8 ≥ 12), detect Brotli, locate the payload.
2. identify — map version_hash to a V8 version with the embedded index; fall back to recomputing the hash when the index misses.
3. deserialize — walk the V8 serialization stream (tags, backrefs, the hot-object ring, plus 6.x's kBackrefWithSkip and variable-length raw) into an object graph.
4. disassemble — decode bytecode against the per-version table; operand sizes, scaling and implicit-register tables come from bytecodes.h.
5. decompile — register IR → structured control flow (if, loops, switch, try) → AST → print; generator/async state machines, completion-code dispatch and class assembly are folded version by version.

Verification

Four gates, each reproducible on its own:

1. Behavior matrix (scripts/verify_behavior.sh) — every fixture is compiled to .jsc with that Node version, decompiled by jscd (with the runnable prelude), gated on syntax, then the product and the original function are compared case by case on their return values. Two structural gates ride along: the default (non---runtime) product may not lose top-level declarations (AST-layer DCE guard), and known-fails are counted separately so they cannot mask regressions.
2. Whole-script diffing (scripts/script_diff.js) — a complete script is run under node and stdout/exit code compared (covers "top level is statements only / const only / class only / async", which target-style fixtures cannot reach).
3. Corpus sweeps (scripts/verify_samples.py) — large sample sets × many versions: compile → decompile → node --check → load in a vm with a minimal test262 stub (a ReferenceError naming anything we generate — __*, _anon_*, ctx*, phi* — is a bug).
4. Unit tests and static checks — cargo test (56 tests) + cargo clippy --all-targets (0 warnings) + cargo build (0 warnings) + the dependency-free end-to-end smoke scripts/ci_smoke.sh (compile → decompile → syntax-gate → run the 5 whole-script fixtures).

cargo test                                              # 56 unit tests
bash scripts/verify_behavior.sh 8.17.0 10.24.1 12.22.12 14.21.3 16.20.2 18.20.8 20.20.2 22.12.0 24.12.0
python3 scripts/verify_samples.py 20.20.2 --limit 200    # corpus; also --offset, --samples

Fixtures are compiled the same way bytenode does it (same flags, createCachedData() — see scripts/mkcorpus.js); the transcript at the top uses real bytenode 1.7.0.

Numbers (all reproducible with the scripts above; the matrix rows are freshly measured):

• skip (8 cells) marks fixtures whose source syntax needs a newer parser (?./?? on Node 8/10/12.15, BigInt literals on 8.17), declared as min_node in tests/fixtures/behav/cases.json and counted separately from failures.
• compile-fail cells in the corpus are sample sources the version's own parser rejects (modern syntax — 64 of them on 8.17); the 0 syntax / 0 decompile claim is about the products.
• No known-fail remains. iter_no_extra_close covers a case whose native semantics differ between V8 versions (for (const v of [1,1,2]) { if (v === 2) continue; } calls iterator.return() once on 6.2/6.8 and never on 7.8+): such fixtures are marked same_node_original in cases.json, so the original is run with the same Node version the artifact was compiled with — the product must reproduce its own version's behavior, which it does on all 31 lines.
• The IteratorClose epilogue that used to swallow loop-body exceptions, and both try/finally completion-code gaps, are fixed — iter_close and finally_return pass.

Behavior fixtures (each runs on all 31 lines): arith branch loop_for loop_while strings array_ops object_ops switch_case try_catch recursion closure class_basic destructure template spread_rest for_of_in arrow_opt generator operators string_regex yield_expr async_await async_try optional_chain twoclasses call_args3 call_once finally_return finally_solo delete_result num_literals try_catch_after iter_close param_defaults typeof_flags iter_no_extra_close

Whole-script fixtures (stdout + exit code compared): top_stmt top_const top_var top_class top_async

One corpus line in one run: ≈ 2,800 products / 33.5 MB / ≈ 700 k lines of decompiled code.

mise.toml pins the Node versions the harness uses by default (10.24.1 → 24.12.0); the matrix also uses older and newer lines — install the remaining 23 with:

mise install node@8.17.0 node@12.5.0 node@12.9.0 node@12.15.0 node@13.14.0 node@14.0.0 \
  node@14.4.0 node@14.5.0 node@14.6.0 node@15.14.0 node@16.3.0 node@16.5.0 node@16.8.0 \
  node@16.9.0 node@17.1.0 node@17.9.1 node@18.2.0 node@19.1.0 node@19.9.0 node@21.7.3 \
  node@23.11.1 node@25.9.0 node@26.10.0

Repository layout

src/              header, serializer, bytecode, disasm, decompile, CLI (`src/help.rs` holds the help text)
tables/           per-V8 tables: opcode operands, roots, scope-info layout, runtime names,
                  read-only-heap name maps (`ro_map_*.json`) + manifest.json
scripts/          table codegen, corpus builders, verification harnesses, release.sh, ci_smoke.sh
tests/            unit + integration tests, and fixtures (compiled to .jsc on the fly)
docs/             VERSIONS.md (per-version engineering notes), ARCHITECTURE.md, DECOMPILE.md,
                  stream-format.md
.github/          tag-triggered release workflow: 6 platforms, bare binaries, described releases
CONTRIBUTING.md   build, the gates a change must pass, how to add a fixture

Limitations

• No source text and no original identifiers; names are reconstructed.
• V8 builtins appear as __runtime.* / __intrinsic.* calls with minimal stubs.
• Scope slots that cannot be named print as __ctx.ctxN. Built-in names on Node 22+ need a read-only-heap name table: the embedded ones are macOS-only (see Usage), so on Linux/Windows build your own (jscd ro-map) or live with <ro…> placeholders.
• decompile targets readable, runnable output, not byte-identical round-tripping.

License

MIT — see LICENSE.

Acknowledgements

bytenode for the packaging this tool targets; View8 for the disassembly format conventions; swc for the AST-level cleanup (a Rust port of terser's copy propagation).