jscd

Decompila i file .jsc compilati con bytenode riportandoli a JavaScript. Solo parsing statico: un unico binario in puro Rust — nessuna V8 modificata, nessun runtime Node, nessuna rete.

Supporta Node 8.0.0 → 26.10.0 (510 release / 36 minor di V8); ≈ 25k file .jsc superano i test con 0 fallimenti (31 linee Node × 41 fixture, compilate con i flag di bytenode 1.7.0); due livelli di ottimizzazione (register folding → swc copy propagation) rendono leggibile il sorgente decompilato.

English · 中文

Indice: Punti salienti · Avvio rapido · Installazione · Utilizzo · Riferimento CLI · Versioni supportate · Come funziona · Verifica · Struttura del repository · Limitazioni · Contribuire

Punti salienti

• Copertura — ogni release di Node da 8.0.0 → 26.10.0 (510 release / 36 minor di V8) viene identificata; una V8 al di fuori delle tabelle è un errore chiaro, non un'ipotesi.
• Output eseguibile — --runtime aggiunge gli stub __runtime così il risultato viene eseguito sotto node; --verify lo sottopone a node --check.
• Output leggibile — due livelli di ottimizzazione ricompongono lo shuffling dei registri del bytecode in espressioni (register folding → swc copy propagation); JSCD_NO_OPT=1 mostra la forma grezza.
• Nomi recuperati — gli slot di scope vengono nominati, i builtin risolti tramite una tabella di nomi in read-only-heap; mai un identificatore che genera ReferenceError.
• Un binario senza dipendenze — puro Rust: niente Node, niente rete, niente V8 modificata; la build Linux è un binario statico da 2.8 MB (UPX).
• Verifica riproducibile — 31 linee Node × 41 fixture confrontate caso per caso, più scansioni del corpus; ogni numero è riproducibile (vedi Verifica).

Avvio rapido

$ 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

I primi byte sono il magic della code-cache in little-endian (cc 05 de c0 = 0xc0de05cc); jscd info hello.jsc decodifica l'intero header (esempio in Usage).

L'output sopra è ciò che viene prodotto dopo entrambi i livelli di ottimizzazione. JSCD_NO_OPT=1 jscd hello.jsc mostra invece la traduzione grezza — lo shuffling dei registri di V8, un'istruzione alla volta.

Su Node 22+ (V8 12.4+) alcuni nomi di proprietà built-in risiedono nell'heap di sola lettura. Per le 29 minor di V8 coperte dalla matrice di comportamento jscd fornisce una tabella di nomi (tables/ro_map_*) e li risolve automaticamente — su macOS, dove quelle tabelle sono state estratte: gli indici dell'heap di sola lettura sono specifici della piattaforma, quindi su altri sistemi costruisci la tua con jscd ro-map e passa --ro-map (JSCD_NO_RO_MAP=1 disattiva la tabella incorporata). Senza una tabella tali nomi appaiono come <ro0_…> placeholder — mai come il nome sbagliato.

Install

macOS / Linux — Homebrew

brew install ejfkdev/tap/jscd

Windows — Scoop

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

Direttamente dall'URL del manifest, senza aggiungere prima il bucket:

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

scoop install ejfkdev/scoop-bucket/jscd non funziona: Scoop risolve bucket/app rispetto ai bucket che hai già aggiunto, non rispetto a un percorso owner/repo.

Binari precompilati — ogni release con tag include eseguibili nudi e pronti all'uso (Linux / macOS / Windows × x64 / arm64; Linux amd64 è una build statica musl, Linux e Windows sono compressi con UPX):

Prendine uno direttamente dalla pagina della release (nessun archivio, nessun installer — il file è l'eseguibile):

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 (qualsiasi piattaforma con Rust 1.96+)

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

Dalla fonte

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

Richiede Rust 1.96+ (swc, l'ottimizzatore JS, necessita di un rustc recente). Nessuna dipendenza di sistema.

Rilascio (maintainer)

scripts/release.sh vX.Y.Z esegue i gate di rilascio (cargo test --release, clippy --all-targets -- -D warnings, e lo smoke end-to-end scripts/ci_smoke.sh — fixture compilate in veri .jsc, decompilate, verificate sintatticamente e confrontate in esecuzione), poi esegue il push di un tag annotato il cui messaggio diventa la descrizione della GitHub Release. Il tag attiva .github/workflows/release.yml, che ricostruisce i sei binari bare elencati sopra. Poi cargo publish su crates.io (release.sh mantiene sincronizzati il tag e la versione in Cargo.toml), e python3 scripts/update_readme_help.py per aggiornare l'help della CLI qui sotto; la Homebrew tap e il Scoop bucket rilevano la nuova release durante la loro esecuzione giornaliera di auto-aggiornamento.

Utilizzo

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