jscd

Обратное преобразование скомпилированных bytenode файлов .jsc обратно в JavaScript. Только статический анализ: один бинарник на чистом Rust — без пропатченного V8, без среды выполнения Node, без сети.

Поддерживает Node 8.0.0 → 26.10.0 (510 релизов / 36 минорных версий V8); ≈ 25 тыс. файлов .jsc проходят тесты с 0 ошибок (31 линия Node × 41 фикстура, скомпилированных с флагами bytenode 1.7.0); два слоя оптимизации (свёртка регистров → копирующее распространение swc) делают декомпилированный исходный код читаемым.

English · 中文

Содержание: Ключевые особенности · Быстрый старт · Установка · Использование · Справочник CLI · Поддерживаемые версии · Как это работает · Проверка · Структура репозитория · Ограничения · Участие в разработке

Ключевые особенности

• Покрытие — каждый релиз Node от 8.0.0 → 26.10.0 (510 релизов / 36 минорных версий V8) определяется; версия V8 вне таблиц — это явная ошибка, а не догадка.
• Запускаемый результат — --runtime добавляет заглушки __runtime, чтобы результат работал под node; --verify прогоняет его через node --check.
• Читаемый результат — два слоя оптимизации сворачивают перестановки регистров байт-кода обратно в выражения (свёртка регистров → копирующее распространение swc); JSCD_NO_OPT=1 показывает исходную форму.
• Восстановленные имена — слоты областей видимости именуются, встроенные функции разрешаются через таблицу имён read-only-heap; никогда не используется идентификатор, вызывающий ReferenceError.
• Один бинарник без зависимостей — чистый Rust: без Node, без сети, без пропатченного V8; сборка для Linux — это статический бинарник размером 2.8 МБ (UPX).
• Воспроизводимая проверка — 31 линия Node × 41 фикстура сравниваются по отдельности, плюс прогоны по корпусу; каждое число можно воспроизвести (см. Проверка).

Быстрый старт

$ 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

Первые байты — это магия кэша кода в little-endian (cc 05 de c0 = 0xc0de05cc); jscd info hello.jsc декодирует весь заголовок (пример в Usage).

Вывод выше — это то, что получается после обоих слоёв оптимизации. JSCD_NO_OPT=1 jscd hello.jsc показывает вместо этого сырую трансляцию — перестановки регистров V8, инструкция за инструкцией.

В Node 22+ (V8 12.4+) некоторые имена встроенных свойств находятся в read-only heap. Для 29 минорных версий V8, покрытых матрицей поведения, jscd поставляет таблицу имён (tables/ro_map_*) и разрешает их автоматически — на macOS, где эти таблицы были извлечены: индексы read-only-heap зависят от платформы, поэтому на других системах создайте свою с помощью jscd ro-map и передайте --ro-map (JSCD_NO_RO_MAP=1 отключает встроенную таблицу). Без таблицы такие имена отображаются как плейсхолдеры <ro0_…> — но никогда как неправильное имя.

Install

macOS / Linux — Homebrew

brew install ejfkdev/tap/jscd

Windows — Scoop

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

Прямо из URL манифеста, без предварительного добавления бакета:

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

scoop install ejfkdev/scoop-bucket/jscd не работает: Scoop разрешает bucket/app относительно уже добавленных вами бакетов, а не относительно пути owner/repo.

Готовые бинарные файлы — каждый помеченный тегом релиз поставляется с готовыми к запуску исполняемыми файлами (Linux / macOS / Windows × x64 / arm64; Linux amd64 — статическая сборка musl, Linux и Windows сжаты UPX):

Возьмите один прямо со страницы релиза (без архива, без установщика — сам файл является исполняемым файлом):

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 (любая платформа с Rust 1.96+)

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

Из источника

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

Требуется Rust 1.96+ (swc, оптимизатор JS, нуждается в свежем rustc). Системные зависимости отсутствуют.

Выпуск релиза (для мейнтейнеров)

scripts/release.sh vX.Y.Z запускает релизные проверки (cargo test --release, clippy --all-targets -- -D warnings, а также сквозной smoke-тест scripts/ci_smoke.sh — фикстуры компилируются в настоящие .jsc, декомпилируются, проверяются на синтаксис и сравниваются при запуске), затем отправляет аннотированный тег, сообщение которого становится описанием GitHub Release. Тег запускает .github/workflows/release.yml, который пересобирает шесть bare-бинарников, перечисленных выше. Затем cargo publish в crates.io (release.sh поддерживает синхронизацию тега и версии в Cargo.toml), и python3 scripts/update_readme_help.py для обновления справки CLI ниже; Homebrew tap и Scoop bucket подхватывают новый релиз во время ежедневного автообновления.

Использование

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