rust-anything
автор: erKam Yaman
English · Türkçe · 简体中文 · 繁體中文 · Deutsch · Français · Русский · Українська · 日本語 · 한국어 · Azərbaycanca · Oʻzbekcha · Қазақша · Кыргызча · Türkmençe · Татарча · ئۇيغۇرچە · Português
Цей переклад підтримує спільнота, тому він може відставати від англійського README.
Перепишіть увесь застосунок на Rust. І щоб він працював на кожному кроці.
CLI, сервери та бібліотеки, частина за частиною, з перевіркою щодо оригіналу на кожному кроці.
Node.js і TypeScript · Python · C · Go · Ruby · Java · PHP і C# у preview
до 20x швидше · 38 251 записаний випадок відтворено · 0 розбіжностей · одна команда
**Перепишіть увесь застосунок на Rust, частина за частиною.** rust-anything записує, що сьогодні робить
ваш застосунок на Node.js (TypeScript/JavaScript), Python, C, Go, Ruby чи Java, а потім перевіряє кожну частину
переписаного на Rust коду щодо цього запису, перш ніж рухатися далі, доки застосунок не стане чистим Rust. CLI, HTTP-сервери
та бібліотеки; Rust пише ваш агент для програмування (або ви самі). Він може виявити лише те, що
покриває запис: див. [Чого він не може виявити](#чого-він-не-може-виявити). Потрібно пришвидшити лише повільну частину?
Портуйте тільки її, один гарячий шлях за раз:
| Реальне навантаження, ті самі результати, що й в оригіналу | Оригінал | З rust-anything |
| --- | ---: | ---: |
| Пошук у бічній панелі x18n, 50 000 ключів (TypeScript, Node) | 10 мс на запит | **0,5 мс: у 20x швидше** |
| Той самий пошук у браузері (wasm, один потік) | 10 мс | **0,95 мс: 11,5x** |
| `slugify` по 20 000 рядків (Python) | 98 мс | **у 17x швидше** |
| `Shellwords.shellescape` зі стандартної бібліотеки Ruby, 50 000 значень | 88 мс | **у 11,8x швидше** |
| `Slugify` по 50 000 рядків (Go) | 49 мс | **у 4x швидше** |
| `slugify` по 50 000 рядків (Java) | 43 мс | **у 3x швидше** |
Виміряно на 4 ядрах; для кожного числа в [`demo/`](../demo) є бенчмарк, який спершу перевіряє,
що результати ідентичні. Викликати Rust окремо для кожної маленької функції зазвичай *повільніше*, ніж JIT;
rust-anything знаходить цикл, який варто перенести, і переносить його.
> rust-anything є незалежним проєктом, не пов'язаним із Rust Project чи Rust Foundation і не схваленим ними.
> «Rust» є торговельною маркою Rust Foundation.
## Швидкий старт
Вставте це в Claude Code, Codex, Cursor або Gemini CLI, і нехай ваш агент усе встановить:
```text
Встанови rust-anything: виконай `cargo install rust-anything`, потім `rust-anything setup`.
Скажи мені, коли тебе треба перезапустити.
```
Або самостійно:
```sh
cargo install rust-anything # з crates.io
rust-anything setup # реєструє його в Claude Code, Codex, Cursor і Gemini CLI
```
Ще немає Rust toolchain? Готові бінарні файли для macOS, Linux і Windows прикріплено до кожного
[релізу на GitHub](https://github.com/erkamyaman/rust-anything/releases), а для JavaScript-проєктів
`npm install -g rust-anything` встановлює той самий бінарний файл.
У Claude Code його також можна встановити як плагін (MCP-сервер і skill; CLI вище
має бути у вашому `PATH`):
```text
/plugin install rust-anything --marketplace erkamyaman/rust-anything
```
`setup` додає MCP-сервер до кожного агента, якого знаходить, і встановлює workflow skill туди, звідки агент
читає skills. Він зберігає інші ваші налаштування, його безпечно запускати повторно, а `--remove` скасовує зміни.
Потім попросіть агента, наприклад:
- *«Перепиши цей CLI на Rust за допомогою rust-anything, від початку до кінця, і доведи, що він поводиться так само.»*
- *«Цей пошук здається повільним. Запусти профілювання з rust-anything і перенеси гарячий цикл у Rust.»*
- *«Сплануй міграцію `src/parser/` на Rust з rust-anything; портуй першу одиницю і доведи її правильність.»*
- *«Порівняй у бенчмарку Rust-порт у `rust/text-rs` з оригіналом і скажи, чи варто його випускати.»*
### Працює з
| Агент | `rust-anything setup` додає |
| --- | --- |
| Claude Code | MCP-сервер у `~/.claude.json`, skill у `~/.claude/skills/` |
| Codex | MCP-сервер у `~/.codex/config.toml`, skill у `~/.codex/skills/` |
| Cursor | MCP-сервер у `~/.cursor/mcp.json` |
| Gemini CLI | MCP-сервер у `~/.gemini/settings.json` |
| Будь-який інший MCP-клієнт | додайте `rust-anything mcp` як stdio-сервер вручну (див. [Встановлення](#встановлення)) |
Перед зміною наявного файлу `setup` зберігає його копію поруч (`.rust-anything.bak`).
Або виконайте кроки самостійно:
```sh
rust-anything profile . -- node bench.mjs # що гаряче і хто це викликає
rust-anything bridge . src/fuzzy.ts --batch fuzzyScore:text
# напишіть src/port.rs (або доручіть агенту), потім:
rust-anything record rust/fuzzy-rs && rust-anything build rust/fuzzy-rs
rust-anything diff rust/fuzzy-rs # кожен записаний випадок має збігтися
rust-anything bench rust/fuzzy-rs # швидше? вердикт скаже
rust-anything gate rust/fuzzy-rs # готово означає, що це проходить
```
rust-anything не перекладає код: Rust пише ваш агент для програмування (Claude Code, Codex, Cursor, ...) або ви
самі. rust-anything дає те, що агент не може надійно вгадати: куди йде час, що портувати
першим і в якому порядку, bridge, щоб решта коду викликала Rust з незмінним API,
точну поведінку, якій має відповідати порт, безпечний спосіб його випустити і gate, який каже, коли порт
готовий.
## Мови
| Мова | Одиниця | Bridge | Хто записує та відтворює |
| --- | --- | --- | --- |
| TypeScript/JavaScript | тека або файл | napi-rs або wasm-bindgen зі згенерованим бінарним wire-форматом; класи та async теж | Node, запускає вихідні файли `.ts` |
| Python | пакет або модуль | PyO3 (abi3), пряме перетворення, типізовані винятки | Python, імпортує оригінал |
| C | файл `.c` | функції `extern "C"` з оригінальними іменами та заголовком | оригінал, скомпільований у спільну бібліотеку, викликається через ctypes, один fork на випадок |
| Go | пакет | типізовані виклики cgo та згенерований бінарний wire-формат, у пакеті з оригінальним API | згенерований Go-драйвер, зібраний як окремий модуль |
| Ruby | файл або тека з функціями модулів | розширення magnus під оригінальними модулями | згенерований Ruby-драйвер |
| Java | пакет методів `public static` | типізований JNI та згенерований бінарний wire-формат, у класах-обгортках з оригінальними методами | згенерований драйвер на reflection |
| PHP (preview) | тека з функціями та методами `public static` | наступний крок: PHP FFI поверх C ABI | цілі застосунки вже зараз: `app record`, `app replay` і front door, для CLI та серверів (`php -S`) |
| C# (preview) | тека з методами `public static` | наступний крок: P/Invoke поверх C ABI | цілі застосунки вже зараз: `app record`, `app replay` і front door, для CLI та серверів ASP.NET (`dotnet .dll`) |
Кожна мова, крім C, також отримує batch-класи (`--batch`): елементи передаються один раз і залишаються в
Rust, а кожен виклик обробляє їх усі на всіх ядрах.
Мова визначається за репозиторієм (`go.mod`, `pom.xml`, `.csproj` або `.sln`,
`pyproject.toml`, `Gemfile`, `composer.json`, `package.json`, інакше за найпоширенішими вихідними файлами);
`--lang` перевизначає її. Типи беруться з коду: типи TS, підказки типів Python, сигнатури C, Go, Java і C#,
теги YARD у Ruby, типи PHP і phpdoc; нетипізовані параметри, які використовуються як числа, виводяться
як числа.
PHP у preview: `analyze` планує PHP-застосунок (пакети Composer і автозавантаження PSR-4, ризики
на кшталт нестрогого порівняння та переповнення цілих чисел у float, відповідність пакетів Composer crate'ам),
а PHP CLI чи сервер можна записати, відтворити і поставити за front door на Rust. Портування його
одиниць у Rust через PHP FFI є наступним кроком ([issue #2](https://github.com/erkamyaman/rust-anything/issues/2)).
C# у preview так само: `analyze` читає проєкти `.csproj` та їхні пакети NuGet
(з відповідними crate'ами), зводить директиви `using` до тек і позначає, що C# робить інакше
(`decimal`, `dynamic`, відкладені запити LINQ, `Task`, `lock`, reflection). C# CLI чи сервер ASP.NET
можна записати, відтворити і поставити за front door на Rust; портування одиниць через P/Invoke
буде наступним.
## Як це працює
```
profile ──> analyze ──> bridge ──> record ──> port.rs ──> diff ──> bench ──> shadow ──> gate
куди йде що Rust що робить ви або кожен швидше? обидва готово =
час портувати crate і оригінал ваш агент записаний вердикт паралельно це
першим обгортка пишете випадок у продакшні проходить
```
Оригінал залишається джерелом істини: `record` запускає його на граничних випадках (і ваших власних вхідних даних) і
зберігає, що він повертає чи викидає; `diff` відтворює кожен випадок на Rust; нічого не випускається, доки
всі вони не збігаються і `gate` не проходить. Код, що викликає, увесь час працює з оригінальним API.
Цілий застосунок проходить той самий цикл одиниця за одиницею, всередині рамки, яка доводить усю
програму ([Портування всього застосунку](#портування-всього-застосунку)):
```
analyze --whole-app ──> app record ──> app front-door ──> для кожної одиниці: цикл вище, потім app wire ──> app lift
форма, кожна що робить Rust володіє gate проходить, тож одиниця відповідає чистий Rust,
залежність, рішення, застосунок точкою входу; з Rust: replay 100%, частка fallback падає доведено
які треба ухвалити ззовні відповідає оригінал replay
```
## Цикл
| Крок | Команда | Що робить |
| --- | --- | --- |
| 0. Профілювання | `rust-anything profile -- node bench.mjs` | Запускає реальне навантаження під профайлером мови (node, cProfile, `go test` pprof, JFR, трейсер Ruby): гарячі функції за інклюзивним часом, їхні виклики і які цикли варто обробляти batch; позначає вже скомпільований код (numba, Cython, JAX), де Rust дає мало |
| 1. План | `rust-anything analyze ` | Одиниці, порядок портування, ризики з `file:line`, bridge для кожної одиниці, відповідність залежностей crate'ам, найкращі перші порти; `--whole-app` додає точки входу та форму застосунку, кожну залежність (імпортовану чи оголошену) з її crate, частини (одиниці, що імпортують одна одну, переносяться разом) і пронумеровані рішення з рекомендованою відповіддю |
| 2. Bridge | `rust-anything bridge ` | Crate з біндингами (`lib.rs`, плюс обгортка, яку завантажує вихідна мова) і заглушками для портування (`port.rs`); `--batch fn:param` додає клас, що тримає багато значень `param` у Rust |
| 3. Запис | `rust-anything record ` | Запускає оригінал на згенерованих граничних випадках (не-ASCII, емодзі, `-0`, `NaN`, цілі там, де очікуються float, ...) і на кожній семантичній пастці в кожному параметрі (довжина і регістр рядків, знакове ділення, межі переповнення, виведення float, порядок у map і сортуванні) і зберігає `cases.jsonl`; `--float-tolerance 1e-9` дозволяє float збігатися в межах цієї частки для числового коду |
| 3. Збірка | `rust-anything build ` | Збирає Rust-частину: `.node`, wasm-пакет, розширення Python або спільну бібліотеку |
| 3. Diff | `rust-anything diff ` | Відтворює записані випадки на Rust, викликаючи його так, як оригінал викликають його клієнти; виводить розбіжності |
| 3. Bench | `rust-anything bench ` | Вимірює час записаних випадків на оригіналі та на Rust, разом із bridge |
| 4. Shadow | `rust-anything shadow ` | Drop-in заміна, яка запускає обидва, повертає результат оригіналу і повідомляє про розбіжності; `RUST_ANYTHING_MODE=old\|shadow\|new` |
| 5. Gate | `rust-anything gate ` | fmt, clippy `-D warnings`, тести, аудит `unsafe`, нічого не лишилося непортованим, записаний невдалий випадок для кожного шляху помилки оригіналу, жодних `unwrap`/`expect`/`panic!` там, де оригінал повертає помилку (якщо не позначено `// INFALLIBLE: `), збірка, API, поведінка |
| Агенти | `rust-anything setup` | Реєструє MCP-сервер (`rust-anything mcp`, кожен крок як інструмент) і workflow skill ([`skills/rust-anything/SKILL.md`](../skills/rust-anything/SKILL.md)) у ваших агентах для програмування |
## Портування всього застосунку
Мета: застосунок на чистому Rust, який поводиться як оригінал, а оригінал зберігається як еталон.
Rust пише ваш агент; rust-anything впорядковує роботу, створює каркас і доводить кожен крок.
[Whole-app skill](../skills/rust-anything/whole-app.md) веде агента крок за кроком, починаючи
з рішень, які можете ухвалити лише ви:
- **Grilling**: агент ставить питання раундами, кожне з рекомендованою відповіддю, доки не буде ухвалено кожне
рішення, від якого залежить порт, і записує кожне як ADR у `rust/DECISIONS.md`,
а `rust/GLOSSARY.md` зіставляє терміни оригіналу з іменами в Rust.
- **Research**: фонові агенти читають першоджерела кожної залежності і пишуть
`rust/research/.md` з кожною знайденою семантичною пасткою.
- **Між сесіями**: `rust/MAP.md` перелічує кожну одиницю з її станом; сесія бере одну одиницю
перед початком, і кожна контрольна точка залишає `rust/HANDOFF.md` для наступної сесії. Одиниці
однієї хвилі можуть портувати паралельно субагенти.
- **Cutover**: агент робить, що може, і пише `rust/cutover.sh`, інтерактивний скрипт для
кроків, які можете виконати лише ви (деплої, DNS, секрети), з можливістю відкату на кожному кроці.
Grilling, research і ці практики адаптовано з
[skills Метта Покока](https://github.com/mattpocock/skills).
Спершу план: `rust-anything analyze . --whole-app` додає форму застосунку (CLI, сервер чи бібліотека)
і точки входу, кожну зовнішню залежність (імпортовану чи оголошену) з її Rust crate і мірою відповідності,
порядок портування у вигляді частин (одиниці, що імпортують одна одну, переносяться разом) і пронумеровані рішення
з рекомендованою відповіддю: які одиниці залишити, заблоковані одиниці, залежності без crate або з частковим crate.
Потім доведіть усю програму ззовні. `record` і `diff` доводять одну одиницю; `app record`
і `app replay` доводять застосунок, для CLI та серверів будь-якою з шести мов (застосунок є
чорною скринькою):
```sh
rust-anything app record . -- python3 cli.py # команда, що запускає оригінал
rust-anything app replay . # оригінал має пройти на 100%
rust-anything app replay . --build "target/release/mytool"
```
- `app record` запускає оригінал на власних задокументованих прикладах застосунку (рядки `$ mytool ...` у
його Markdown і shell-файлах, разом із файлами, які вони згадують), на файлі JSONL з `--inputs`
(`{"name", "args", "stdin", "env", "files"}`) і на семантичних пастках, виведених із цих випадків
(рядки з не-ASCII та емодзі, ділення та остача від’ємних чисел, переповнення, великі та крихітні float,
порядок у map, відсутні файли). Кожен випадок запускається двічі; те, що відрізняється між двома запусками, стає
wildcard `[..]`. `--normalize timestamps|uuids|key-order` або `--normalize name=regex` додає
нормалізатори, які зберігаються разом із випадками.
- Випадки є файлами [trycmd](https://docs.rs/trycmd) у `rust/app-cases/`: `.toml` (argv, env,
код виходу), `.stdin`, `.stdout`, `.stderr`, `.in/` (вхідні файли) і `.out/` (записані файли). Читайте
і редагуйте їх вручну; Rust-тест може запускати їх через `trycmd`, щойно порт матиме бінарний файл.
- `app replay` запускає будь-яку збірку на випадках, виводить `passed/total`, пише
`rust/app-cases/replay-report.md` з diff для кожного невдалого випадку і завершується з ненульовим кодом за будь-якої
розбіжності. Збірка, яка дописує у файл, названий у `RUST_ANYTHING_FALLBACK_LOG` (один рядок на
кожен fallback до оригіналу), як це робить front door нижче, також отримує звіт про частку fallback.
- `app replay --case ` перезапускає один випадок за іменем, яке дає йому звіт: швидкий,
повторюваний цикл для виправлення розбіжності перед повторним запуском усього.
Потім перенесіть точку входу в Rust і передавайте їй команди по одній одиниці:
```sh
rust-anything app front-door . # rust/app: кожна команда запускає оригінал
rust-anything app wire . textkit --command upper # після того, як textkit-rs проходить gate
# напишіть glue-код у rust/app/src/units/textkit.rs, потім:
rust-anything app wire . textkit # знову 100%, нижча частка fallback
```
- `app front-door` створює каркас `rust/app`, бінарний файл на Rust з іменем застосунку: парсер clap для
команд і прапорців із записаних випадків, де кожна команда запускає оригінал з тими самими
argv, stdin і оточенням і передає далі його вивід і код виходу. Кожен fallback
рахується, тож replay щойно створеного front door дає 100% пройдених при 100% fallback (він збирає і
відтворює, щоб це показати). Він ніколи не перезаписує `rust/app`: відтоді код належить вам.
- `app wire --command ` запускає `gate` на crate одиниці (`--skip-gate`, якщо він щойно
пройшов), додає його в `rust/app` як бібліотеку, один раз пише `src/units/.rs`, щоб ви чи ваш
агент його заповнили (розібрати аргументи, викликати `::port`, вивести те, що виводить оригінал),
спрямовує на нього команди, потім збирає і відтворює. `RUST_ANYTHING_UNIT_=original` повертає
підключену одиницю до оригіналу аж до lift.
Підключіть власне ім’я застосунку як команду (`--command mytool`) для argv, що не називає жодної команди: без
аргументів, невідомі команди, помилки використання.
Коли replay проходить з часткою fallback 0 і кожна одиниця проходить gate, зробіть із нього застосунок на чистому Rust:
```sh
rust-anything app lift .
```
- `app lift` відмовляється, доки обидві умови не виконано, і каже, що заважає: випадки, які досі йдуть у fallback,
glue-код, що досі є заглушкою, одиниці, що не проходять gate.
- Спершу на копії він прибирає шлях fallback і перемикачі, перетворює crate кожної одиниці на
звичайну бібліотеку `rust/app` (без `cdylib`, біндингів чи згенерованих обгорток) і додає
`rust/app/tests/app_cases.rs`, який запускає `rust/app-cases` через trycmd під час `cargo test`, тож CI
не потребує нічого, крім cargo.
- Потім він проходить чекліст lift: fmt, clippy `-D warnings` і тести для кожної одиниці та для
`rust/app`, кожна ціль, названа в `rust/DECISIONS.md`, зібрана або перевірена там, де вона встановлена,
файли, що читаються під час виконання, і теки з ресурсами не вбудовано, і replay на чистому бінарному файлі. Лише коли
все це проходить, зміни записуються назад. Оригінал ніколи не змінюється.
### Сервери
Ті самі команди доводять HTTP-сервери. `--http` означає, що команда запускає сервер; порт вона бере
з `PORT` або `{port}` у команді (`--port` для сервера, який завжди слухає той самий
порт):
```sh
rust-anything app record . --http -- node server.js
rust-anything app replay .
rust-anything app front-door . # axum: кожен маршрут проксюється
rust-anything app wire . api --route 'GET /users/{id}' --route '*'
rust-anything app lift .
```
- Запити беруться з рядків `curl` у документації застосунку (`curl -X POST -d ... http://localhost:8080/x`),
з `--inputs` (`{"name", "method", "path", "headers", "body"}`) і з пасток: сегменти шляху та значення query
замінюються тими самими пастками, що й аргументи CLI, тіла запитів пастками для тексту і JSON, плюс
невідомий маршрут. Кожен запуск стартує сервер наново і надсилає запити в порядку імен, тож стан
між запитами зберігається.
- Випадки є файлами `rust/app-cases/http/.toml` (запит, статус і важливі заголовки)
і `.body` (тіло відповіді, з `[..]` там, де два запуски відрізнялися). Date, server та
інші заголовки, специфічні для кожної відповіді, не враховуються; видаліть будь-який рядок заголовка, який вам не важливий.
- Front door є сервером axum, який запускає оригінал на власному порту і проксює
кожен маршрут, на який не відповідає жодна одиниця. `wire --route` приймає маршрути axum: `METHOD /path/{param}`, `/path`
для будь-якого методу, `*` для всього іншого; glue-код отримує маршрут, його параметри і
запит. `lift` прибирає проксі; після цього HTTP-випадки запускаються в CI через `app replay`.
### Бібліотеки
Бібліотека не має процесу, який можна відтворити: її публічний API і є front door, а записані
випадки кожної одиниці є доказом.
```sh
rust-anything app front-door . # rust/app: Rust crate з публічним API
# кожна одиниця проходить цикл: bridge, record, port.rs, build, diff, gate; потім:
rust-anything app wire . textkit-rs # реекспортується з rust/app; оригінал імпортує свій shadow
rust-anything app replay . # випадки кожної підключеної одиниці; fallback = експорти, що досі в оригіналі
rust-anything app lift .
```
- `app front-door` знаходить публічний API (експорти кожної одиниці), коли в репозиторії немає `main`
і немає сервера (інакше `--library`), і створює `rust/app` як бібліотечний crate. Кожна підключена
одиниця стає його модулем: `pub use textkit_rs::port as textkit;`.
- `app wire` приймає crate, створений `bridge`, запускає `gate` і пише shadow drop-in одиниці:
оригінальний пакет імпортує його замість одиниці, тож його клієнти зберігають оригінальний API і
потрапляють у Rust. `RUST_ANYTHING_UNIT_=original` повертає одиницю назад (C: зібрати без
прапорців shadow).
- `app replay` проганяє записані випадки кожної підключеної одиниці через її біндинги. Частка fallback
це частка публічних експортів, на які Rust ще не відповідає: непідключені одиниці та експорти, які `bridge` залишає
мовою оригіналу.
- `app lift` потребує fallback 0 і проходження `gate` кожною одиницею; він прибирає біндинги, обгортки і
shadow з одиниць і залишає `rust/app` однією бібліотекою на чистому Rust. Він не чіпає жоден
`port.rs`, тож випадки, що збіглися через біндинги, і далі його описують; чекліст
попереджає про файли оригіналу, які досі імпортують shadow.
Усі п’ять також є MCP-інструментами: `app_record`, `app_replay`, `app_front_door`, `app_wire` і
`app_lift`.
## Приклад із практики: ядро x18n
Усі 29 функцій ядра x18n, які можна перенести без зміни API, портовано з rust-anything:
кожен gate проходить, і 7 925 записаних випадків точно збігаються. Потім `rust-anything bench` показав, що порти
повільніші за TS, якщо викликати їх із JS, бо bridge коштує більше, ніж сама робота. Повний звіт:
[`demo/x18n-core`](../demo/x18n-core/README.md). Урок вбудовано в інструмент: вимірюйте через `bench`, перш ніж
випускати порт.
## Гарячі шляхи: тримайте дані в Rust
Порт, який викликається для кожного елемента окремо, платить за bridge за кожен елемент і програє JIT. Виграє
перенесення циклу: `profile` знаходить його, а `--batch` генерує клас, який приймає елементи один раз
і за кожен виклик проганяє функцію по всіх них, на всіх ядрах, з результатами у typed array.
```sh
rust-anything profile ../x18n -- node --experimental-strip-types $PWD/demo/x18n-search/search.ts .
# -> fuzzyScore: чверть усього запуску, викликається для кожного ключа з `matched`: обробляйте batch
rust-anything bridge ../x18n packages/core/src/fuzzy.ts --batch fuzzyScore:text
```
```js
const search = new FuzzyScoreBatch(keys) // один раз
const order = search.rank(query, 0) // на кожне натискання: індекси, найкращі першими
```
Структура `FuzzyScoreIndex` у `port.rs` замінює типовий цикл таким, що готує
елементи один раз і може ранжувати сам (`rank`): він зберігає ключі в нижньому регістрі з маскою символів
для кожного, таблицю першої позиції кожного поширеного символу в кожному ключі (запит з однієї літери є одним
стовпцем) і збіги останнього запиту (введення `se` після `s` переоцінює лише те, що знайшов `s`). На
пошуку в бічній панелі x18n по 50 000 ключів, з введенням по літері, з ідентичними результатами:
| | На запит | порівняно з TS |
| --- | ---: | ---: |
| TS: `map(fuzzyScore)`, filter, sort | 10 мс | 1x |
| TS з тим самим звуженням, що й в індексі | 4,1-5,4 мс | 2x |
| Той самий порт, викликаний для кожного ключа | - | 0,2-0,4x |
| `FuzzyScoreBatch`, типовий індекс (4 ядра) | 5,1 мс | 1,7x |
| `FuzzyScoreBatch` з `FuzzyScoreIndex` (napi, 4 ядра) | 0,45-0,56 мс | **18-22x** |
| Те саме з wasm (один потік) | 0,95 мс | **11,5x** |
Порівняно з TS, який робить те саме звуження, Rust усе одно у 7-12x швидший (wasm у 5x). Перетворюйте повернуті
індекси на ключі простим циклом: `Array.from(order, i => keys[i])` коштував у 20x більше, 0,4 мс.
Кожна мова отримує batch, і він перемагає оригінал навіть там, де порти з викликом на кожен елемент програють. Та
сама робота на 4 ядрах, ідентичні результати і помилки (бенчмарки в теці кожного демо):
| Мова | Навантаження | Оригінал | Порт з викликом на елемент vs оригінал | Batch vs оригінал |
| --- | --- | ---: | ---: | ---: |
| TS | пошук x18n, 50 000 ключів | 10 мс | 0,2-0,4x | **20x** |
| Python | `slugify`, 20 000 рядків | 98 мс | - | **17x** |
| Ruby | `slugify`, 20 000 рядків | 110 мс | - | **12,7x** |
| Ruby | `shellescape` (stdlib), 50 000 змішаних значень | 88 мс | - | **11,8x** |
| Go | `Slugify`, 50 000 рядків | 49 мс | 0,93x | **4x** |
| Java | `slugify`, 50 000 рядків | 43 мс | 0,68x | **3x** |
Скомпільовані оригінали виграють менше: робота на один елемент і так швидка, тож batch виграє приблизно в кількість
ядер. Batch crate'и виділяють пам’ять через mimalloc: із системним алокатором batch на Go був повільнішим за
один потік. Демо: [`demo/x18n-search`](../demo/x18n-search/README.md).
## Реальний код шістьма мовами
`path` з Go, `shellwords` з Ruby, `colorsys` з Python, поведінка JDK і glibc за невеликими
фасадами: кожен порт проходить свій gate, загалом 13 010 записаних випадків. Ці запуски знайшли і виправили
баги в rust-anything (float, що відрізнялися на один ULP через `serde_json`, падіння C під час запису,
нетипізований код, що отримував сміттєві вхідні дані). При виклику для кожної функції порт Ruby працює у 4,4x швидше за
Ruby, а порт Python у 1,35x швидше за CPython, тоді як листові функції Go і Java залишаються швидшими
у своїй мові; як batch, виграють усі (див. таблицю вище).
Звіт: [`docs/real-world-languages.md`](./real-world-languages.md).
## Приклад: реальний модуль з x18n
`packages/core/src/fuzzy.ts` з [x18n](https://github.com/x18n-dev/x18n), портований обома способами в
[`demo/`](../demo):
```sh
rust-anything analyze ../x18n # fuzzy.ts: готовий, wasm-bindgen (core працює в браузерах)
rust-anything bridge ../x18n packages/core/src/fuzzy.ts --out demo/fuzzy-rs
rust-anything record demo/fuzzy-rs --count 2000
# напишіть src/port.rs
rust-anything gate demo/fuzzy-rs
```
Перший порт, який індексував за Rust `char`, проходив прості тести, але не пройшов `diff`:
```
198/200 cases match
- fuzzyScore("b😀", "a😀b😀c"): expected {"ok":1997}, got {"ok":1998}
```
`indexOf` у JS рахує кодові одиниці UTF-16, тож емодзі займає дві позиції. Порт у
`demo/*/src/port.rs` використовує згенеровані допоміжні функції `utf16` і проходить 2000/2000 випадків і gate,
як napi-rs (`demo/fuzzy-napi`) і як wasm-bindgen (`demo/fuzzy-rs`).
План, який rust-anything пише для всього x18n: [`docs/examples/x18n.md`](./examples/x18n.md).
## Встановлення
```sh
cargo install --path .
```
`record`, `diff` і `bench` запускають оригінал у його власному середовищі виконання: Node 22.6+ для TS (він запускає
вихідні файли `.ts` напряму), Python 3.9+ для Python і C (ctypes), Go 1.21+, Ruby 3+, JDK 17+
(`javac` і `java`). Для C також потрібен компілятор C. Для wasm bridge також потрібні `rustup target add wasm32-unknown-unknown` і
`cargo install wasm-bindgen-cli --version --locked`; `build` називає
точну версію.
Для агентів `rust-anything setup` реєструє все (див. Швидкий старт). Щоб натомість вручну додати MCP-сервер до
одного проєкту (`.mcp.json`):
```json
{ "mcpServers": { "rust-anything": { "command": "rust-anything", "args": ["mcp"] } } }
```
## Що вирішує `bridge`
- Експорти, які не можуть пройти через bridge, залишаються мовою оригіналу із зазначенням причини, а shadow-модуль
реекспортує оригінал. Для TS це:
функції, що приймають або повертають функції, генератори та ітератори, RegExp, перевірки `instanceof`,
generics і значення, чиї типи (з урахуванням імпортів, реекспортів і `extends`) містять
функції. `--keep "name: reason"` залишає більше, наприклад код, що залежить від даних `Intl`.
- Типи TS відображаються на типи Rust, з type alias, розв’язаними через імпорти, і типами параметрів,
виведеними зі значень за замовчуванням; структуровані значення передаються через згенерований бінарний wire-формат (JSON лише
як запасний варіант для форм, які wire-формат не моделює).
- JSON не може виразити `undefined`, NaN, Infinity, -0 чи поодинокі сурогати: структуровані значення несуть
маркери (`{"$undefined": true}`, `{"$num": "NaN"}`, `{"$utf16": [...]}`), які перекладає згенерований
`index.cjs`, з допоміжними функціями в `js.rs` crate'а.
`record` запускає вихідні файли TS як є: resolve hook у Node обробляє імпорти в стилі бандлера
(`./errors` до `./errors.ts`), `--resolve-from` надає npm-пакети, коли в репозиторії їх не
встановлено, а TS, який потребує трансформації (enum, parameter properties), запускається повторно з
`--experimental-transform-types`.
## На що дивиться `analyze`
- Пакети (`package.json`) і вихідні файли; пропускає `node_modules`, результати збірки, фікстури,
playground'и, конфігурації інструментів. Блоки `