jscd

Reverse bytenode-kompilierte .jsc-Dateien zurück zu JavaScript. Nur statisches Parsen: ein reines Rust-Binary — kein gepatchtes V8, keine Node-Runtime, kein Netzwerk.

Unterstützt Node 8.0.0 → 26.10.0 (510 Releases / 36 V8-Minors); ≈ 25k .jsc-Dateien bestehen die Tests mit 0 Fehlern (31 Node-Zeilen × 41 Fixtures, kompiliert mit den Flags von bytenode 1.7.0); zwei Optimierungsschichten (Register Folding → swc Copy Propagation) machen den dekompilierten Quellcode lesbar.

English · 中文

Inhalt: Highlights · Schnellstart · Installation · Verwendung · CLI-Referenz · Unterstützte Versionen · Funktionsweise · Verifikation · Repository-Layout · Einschränkungen · Mitwirken

Highlights

• Abdeckung — jedes Node-Release von 8.0.0 → 26.10.0 (510 Releases / 36 V8-Minors) wird identifiziert; ein V8 außerhalb der Tabellen ist ein klarer Fehler, keine Vermutung.
• Lauffähige Ausgabe — --runtime fügt die __runtime-Stubs hinzu, damit das Ergebnis unter node läuft; --verify schickt es durch node --check.
• Lesbare Ausgabe — zwei Optimierungsschichten falten Bytecode-Register-Shuffling zurück in Ausdrücke (Register Folding → swc Copy Propagation); JSCD_NO_OPT=1 zeigt die Rohform.
• Namen wiederhergestellt — Scope-Slots werden benannt, Builtins über eine Read-only-Heap-Namenstabelle aufgelöst; niemals ein Identifier, der ReferenceError wirft.
• Ein abhängigkeitsfreies Binary — reines Rust: kein Node, kein Netzwerk, kein gepatchtes V8; der Linux-Build ist ein 2,8 MB statisches Binary (UPX).
• Reproduzierbare Verifikation — 31 Node-Zeilen × 41 Fixtures Fall für Fall verglichen, plus Corpus- Sweeps; jede Zahl ist wiederholbar (siehe Verifikation).

Schnellstart

$ 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

Die ersten Bytes sind der Code-Cache-Magic-Wert in Little-Endian (cc 05 de c0 = 0xc0de05cc); jscd info hello.jsc dekodiert den gesamten Header (Beispiel unter Usage).

Die obige Ausgabe ist das, was nach beiden Optimierungsschichten herauskommt. JSCD_NO_OPT=1 jscd hello.jsc zeigt stattdessen die rohe Übersetzung — V8s Register-Shuffling, eine Anweisung nach der anderen.

Unter Node 22+ (V8 12.4+) liegen einige eingebaute Property-Namen im Read-only-Heap. Für die 29 V8- Minor-Versionen, die von der Verhaltensmatrix abgedeckt werden, liefert jscd eine Namenstabelle (tables/ro_map_*) mit und löst sie automatisch auf — unter macOS, wo diese Tabellen extrahiert wurden: Read-only-Heap-Indizes sind plattformspezifisch, daher erstellen Sie auf anderen Systemen Ihre eigene mit jscd ro-map und übergeben --ro-map (JSCD_NO_RO_MAP=1 schaltet die eingebettete Tabelle ab). Ohne eine Tabelle erscheinen solche Namen als <ro0_…> Platzhalter — niemals als der falsche 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

Direkt von der Manifest-URL, ohne zuerst den Bucket hinzuzufügen:

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

scoop install ejfkdev/scoop-bucket/jscd funktioniert nicht: Scoop löst bucket/app gegen bereits hinzugefügte Buckets auf, nicht gegen einen owner/repo-Pfad.

Vorkompilierte Binärdateien — jedes getaggte Release liefert nackte, sofort ausführbare Programme (Linux / macOS / Windows × x64 / arm64; Linux amd64 ist ein statischer musl-Build, Linux und Windows sind UPX-komprimiert):

Lade eine direkt von der Release-Seite herunter (kein Archiv, kein Installer — die Datei ist die ausführbare Datei):

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 (jede Plattform mit Rust 1.96+)

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

Aus Quelle

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

Erfordert Rust 1.96+ (swc, der JS-Optimierer, benötigt einen aktuellen rustc). Keine Systemabhängigkeiten.

Veröffentlichung (Maintainer)

scripts/release.sh vX.Y.Z führt die Release-Gates aus (cargo test --release, clippy --all-targets -- -D warnings und den End-to-End-Smoke-Test scripts/ci_smoke.sh — Fixtures zu echten .jsc kompiliert, dekompiliert, syntax-geprüft und laufzeit-verglichen), und pusht dann einen annotierten Tag, dessen Nachricht zur GitHub-Release-Beschreibung wird. Der Tag löst .github/workflows/release.yml aus, welcher die sechs oben aufgeführten Bare-Binaries neu baut. Dann cargo publish zu crates.io (release.sh hält den Tag und die Cargo.toml-Version synchron), und python3 scripts/update_readme_help.py, um die CLI-Hilfe unten zu aktualisieren; der Homebrew-Tap und der Scoop-Bucket greifen die neue Version bei ihrem täglichen Auto-Update-Lauf auf.

Verwendung

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>`)