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 кодын сезнең программалау агенты (яки сез үзегез) яза. Ул язма
нәрсәне колачлаганын гына тотып кала ала: [Ул нәрсәне тотып кала алмый](#ул-нәрсәне-тотып-кала-алмый) бүлеген карагыз. Бары тик әкрен өлешне генә тизләтергә кирәкме?
Шуны гына күчерегез, бер тапкырда бер кайнар юл (hot path):
| Чын эш йөкләмәсе, нәтиҗәләр оригиналдагы кебек | Оригинал | rust-anything белән |
| --- | ---: | ---: |
| x18n ян панелендәге эзләү, 50 000 ачкыч (TypeScript, Node) | бер сорауга 10 мс | **0,5 мс: 20x тизрәк** |
| Шул ук эзләү браузерда (wasm, бер агым) | 10 мс | **0,95 мс: 11,5x** |
| 20 000 юлга `slugify` (Python) | 98 мс | **17x тизрәк** |
| Ruby стандарт китапханәсеннән `Shellwords.shellescape`, 50 000 кыйммәт | 88 мс | **11,8x тизрәк** |
| 50 000 юлга `Slugify` (Go) | 49 мс | **4x тизрәк** |
| 50 000 юлга `slugify` (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'ны агент skill'ларны укыган урынга
урнаштыра. Ул сезнең башка көйләнмәләрегезне саклый, аны кабат җибәрү куркынычсыз, ә `--remove` аны кире кайтара.
Аннары агентыгыздан сорагыз, мәсәлән:
- *"Бу CLI'ны rust-anything ярдәмендә башыннан ахырына кадәр Rust телендә яңадан яз һәм аның шулай ук эшләвен исбатла."*
- *"Бу эзләү әкрен кебек. Аны rust-anything белән профильлә һәм кайнар циклны Rust'ка күчер."*
- *"rust-anything белән `src/parser/` папкасын Rust'ка күчерүне планлаштыр; беренче берәмлекне күчер һәм исбатла."*
- *"`rust/text-rs` эчендәге Rust портын оригинал белән бенчмаркта чагыштыр һәм аны чыгарыргамы икәнен әйт."*
### Кайсы агентлар белән эшли
| Агент | `rust-anything setup` нәрсә өсти |
| --- | --- |
| Claude Code | `~/.claude.json` эчендә MCP сервер, `~/.claude/skills/` эчендә skill |
| Codex | `~/.codex/config.toml` эчендә MCP сервер, `~/.codex/skills/` эчендә skill |
| Cursor | `~/.cursor/mcp.json` эчендә MCP сервер |
| Gemini CLI | `~/.gemini/settings.json` эчендә MCP сервер |
| Башка теләсә нинди 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 агент ышанычлы итеп чамалый алмаган нәрсәләрне бирә: вакыт кая китә, нәрсәне
беренче һәм нинди тәртиптә күчерергә, калган код Rust'ны API үзгәрмичә чакырсын өчен bridge,
порт туры килергә тиешле төгәл тәртип, аны чыгаруның куркынычсыз ысулы һәм порт кайчан
әзер икәнен әйтүче gate.
## Телләр
| Тел | Берәмлек | Bridge | Кем язып ала һәм кабат уйната |
| --- | --- | --- | --- |
| TypeScript/JavaScript | папка яки файл | ясалган бинар wire форматлы napi-rs яки wasm-bindgen; класслар һәм async та керә | Node, `.ts` чыганакларын җибәреп |
| Python | пакет яки модуль | PyO3 (abi3), туры үзгәртү, типлы исключениеләр | Python, оригиналны импортлап |
| C | `.c` файл | оригинал исемле `extern "C"` функцияләр һәм header | уртак китапханәгә компиляцияләнгән оригинал, ctypes аша чакырыла, һәр очракка бер fork |
| Go | пакет | типлы cgo чакырулары һәм ясалган бинар wire формат, оригинал API'лы пакетта | ясалган Go драйверы, аерым модуль итеп җыела |
| Ruby | модуль функцияләре булган файл яки папка | оригинал модульләр астында magnus киңәйтмәсе | ясалган Ruby драйверы |
| Java | `public static` методлар пакеты | типлы JNI һәм ясалган бинар wire формат, оригинал методлы wrapper класслар эчендә | ясалган reflection драйверы |
| PHP (preview) | функцияләр һәм `public static` методлар папкасы | киләсе адым: C ABI өстендә PHP FFI | бүген үк бөтен кушымталар: `app record`, `app replay` һәм front door, CLI һәм серверлар өчен (`php -S`) |
| C# (preview) | `public static` методлар папкасы | киләсе адым: C ABI өстендә P/Invoke | бүген үк бөтен кушымталар: `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 type hints, C, Go, Java һәм C#
сигнатуралары, Ruby YARD теглары, PHP типлары һәм phpdoc; сан итеп кулланылган типсыз параметрлар
сан дип чыгарыла.
PHP preview рәвешендә: `analyze` PHP кушымтасын планлаштыра (Composer пакетлары һәм PSR-4 autoloading, катгый булмаган
чагыштыру һәм бөтен саннарның float'ка ташып чыгуы кебек куркынычлар, Composer пакетларына туры килгән crate'лар),
ә PHP CLI яки серверны язып алып, кабат уйнатып, Rust front door артына куеп була. Аның
берәмлекләрен PHP FFI аша Rust'ка күчерү киләсе адым ([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
серверын язып алып, кабат уйнатып, Rust front door артына куеп була; берәмлекләрне P/Invoke аша күчерү
киләсе адым.
## Ничек эшли
```
profile ──> analyze ──> bridge ──> record ──> port.rs ──> diff ──> bench ──> shadow ──> gate
вакыт беренче Rust crate оригинал сез яки язылган тизрәкме? икесе дә бу узса,
кая нәрсәне һәм нәрсә агентыгыз һәр нәтиҗә янәшә эш
китә күчерергә wrapper эшли яза очрак production бетте
```
Оригинал хакыйкать чыганагы булып кала: `record` аны чик очракларда (һәм сезнең үз кертмәләрегездә) җибәрә һәм
ул нәрсә кайтарганын яки нинди хата ыргытканын саклый; `diff` һәр очракны Rust'ка карата кабат уйната; барысы да
туры килмичә һәм `gate` узмыйча бернәрсә дә чыгарылмый. Чакыручы код бөтен вакыт оригинал API'ны куллана.
Бөтен кушымта да шул ук циклны берәмлекләп уза, бөтен программаны исбатлаучы рамка эчендә
([Бөтен кушымтаны күчерү](#бөтен-кушымтаны-күчерү)):
```
analyze --whole-app ──> app record ──> app front-door ──> һәр берәмлеккә: өстәге цикл, аннары app wire ──> app lift
форма, һәр кушымта керү ноктасы gate узды, димәк берәмлек Rust'та саф 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 ` | Bindings булган crate (`lib.rs`, өстәвенә чыганак тел йөкли торган wrapper) һәм күчерү өчен stub'лар (`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**: агент турлап сораулар бирә, һәрберсе тәкъдим ителгән җавап белән, порт бәйле булган һәр
карар хәл ителгәнче, һәм һәрберсен `rust/DECISIONS.md` эченә ADR итеп яза,
ә `rust/GLOSSARY.md` оригинал терминнарын Rust исемнәренә туры китерә.
- **Research**: фон агентлары һәр бәйлелекнең беренчел чыганакларын укый һәм табылган һәр семантик тозак белән
`rust/research/.md` яза.
- **Сессияләр арасында**: `rust/MAP.md` һәр берәмлекне аның халәте белән күрсәтә; сессия эшне башлаганчы
бер берәмлекне үзенә ала, һәм һәр контроль нокта киләсе сессия өчен `rust/HANDOFF.md` калдыра. Бер
дулкындагы берәмлекләрне субагентлар параллель күчерә ала.
- **Cutover**: агент булдыра алганын эшли һәм `rust/cutover.sh` яза, бу бары тик сез генә башкара ала торган
адымнар (deploy, DNS, серләр) өчен интерактив скрипт, һәр адымда кире кайту юлы белән.
Grilling, research һәм бу практикалар
[Matt Pocock skill'ларыннан](https://github.com/mattpocock/skills) җайлаштырылган.
Башта план: `rust-anything analyze . --whole-app` кушымтаның формасын (CLI, сервер яки китапханә)
һәм керү нокталарын, һәр тышкы бәйлелекне (импортланган яки игълан ителгән) аның Rust 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` оригиналны кушымтаның үз документлаштырылган мисалларында (аның Markdown һәм shell файлларындагы
`$ mytool ...` юллары, алар искә алган файллар белән), `--inputs` JSONL файлында
(`{"name", "args", "stdin", "env", "files"}`) һәм шул очраклардан чыгарылган семантик тозакларда
(ASCII булмаган һәм эмодзи юллар, тискәре бүлү һәм модуль, ташу, зур һәм бик кечкенә float'лар,
map тәртибе, юк файллар) җибәрә. Һәр очрак ике тапкыр җибәрелә; ике җибәрү арасында аерылган нәрсә
`[..]` wildcard була. `--normalize timestamps|uuids|key-order` яки `--normalize name=regex`
очраклар белән бергә саклана торган нормализаторлар өсти.
- Очраклар `rust/app-cases/` эчендәге [trycmd](https://docs.rs/trycmd) файллары: `.toml` (argv, env,
чыгу коды), `.stdin`, `.stdout`, `.stderr`, `.in/` (керүче файллар) һәм `.out/` (язылган файллар). Аларны
кулдан укыгыз һәм үзгәртегез; портның бинар файлы булгач, Rust тесты аларны `trycmd` белән җибәрә ала.
- `app replay` теләсә нинди җыелманы очракларга карата җибәрә, `passed/total` бастыра,
һәр уңышсыз очрак өчен diff белән `rust/app-cases/replay-report.md` яза һәм теләсә нинди туры килмәүдә
нульдән башка код белән чыга. `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 бинар файлы булган `rust/app` каркасын ясый: язып алынган очраклардагы
командалар һәм флаглар өчен clap парсеры, анда һәр команда оригиналны шул ук
argv, stdin һәм әйләнә-тирә белән җибәрә һәм аның чыгышын һәм чыгу кодын үткәрә. Һәр fallback
санала, шуңа күрә яңа front door'ны кабат уйнату 100% fallback белән 100% уңыш бирә (моны күрсәтү өчен ул җыя һәм
кабат уйната). Ул `rust/app`ны беркайчан да өстән язмый: шуннан соң код сезнеке.
- `app wire --command ` берәмлек crate'ында `gate` җибәрә (әле генә узган булса, `--skip-gate`),
аны `rust/app` эченә китапханә итеп өсти, сез яки агентыгыз тутырсын өчен `src/units/.rs` файлын бер тапкыр яза
(аргументларны тарката, `::port` чакыра, оригинал бастырганны бастыра),
командаларны аңа юнәлтә, аннары җыя һәм кабат уйната. `RUST_ANYTHING_UNIT_=original`
тоташтырылган берәмлекне lift'ка кадәр оригиналга кире җибәрә.
Бернинди команда атамаган argv өчен (аргументсыз, билгесез командалар, куллану хаталары) кушымтаның үз исемен
команда итеп тоташтырыгыз (`--command mytool`).
Replay 0 fallback өлеше белән узганда һәм һәр берәмлек gate узганда, аны саф Rust кушымтасына әйләндерегез:
```sh
rust-anything app lift .
```
- `app lift` ике шарт та үтәлгәнче баш тарта һәм нәрсә комачаулаганын әйтә: әле дә fallback'ка китүче очраклар,
әле дә stub булып калган glue коды, gate узмаган берәмлекләр.
- Башта күчермәдә ул fallback юлын һәм kill switch'ларны бетерә, һәр берәмлек crate'ын
`rust/app`ның гади китапханәсенә әйләндерә (`cdylib`, bindings яки ясалган wrapper'ларсыз) һәм
`rust/app/tests/app_cases.rs` өсти, ул `cargo test` вакытында `rust/app-cases`ны trycmd белән җибәрә, шуңа күрә CI'га
cargo'дан башка бернәрсә дә кирәкми.
- Аннары ул lift чеклистын уза: һәр берәмлектә һәм `rust/app`та fmt, clippy `-D warnings` һәм тестлар,
`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: һәр маршрут proxy аша
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` (сорау, статус һәм мөһим header'лар)
һәм `.body` (җавап эчтәлеге, ике җибәрү аерылган урында `[..]` белән). Date, server һәм
һәр җавапка хас башка header'лар исәпкә алынмый; сезгә мөһим булмаган теләсә нинди header юлын бетерегез.
- Front door ул axum сервер, ул оригиналны үз портында җибәрә һәм бер берәмлек тә җавап бирмәгән
һәр маршрутны proxy аша үткәрә. `wire --route` axum маршрутларын ала: `METHOD /path/{param}`, теләсә нинди метод өчен `/path`,
калган бар нәрсә өчен `*`; glue коды маршрутны, аның параметрларын һәм
сорауны ала. `lift` proxy'ны бетерә; аннан соң HTTP очраклар CI'да `app replay` белән эшли.
### Китапханәләр
Китапханәнең кабат уйнатырлык процессы юк: аның ачык API'сы front door, ә һәр берәмлекнең язып алынган
очраклары дәлил.
```sh
rust-anything app front-door . # rust/app: ачык API'лы Rust crate
# һәр берәмлек цикл аша: bridge, record, port.rs, build, diff, gate; аннары:
rust-anything app wire . textkit-rs # rust/app'тан re-export; оригинал үзенең shadow'ын импортлый
rust-anything app replay . # һәр тоташтырылган берәмлекнең очраклары; fallback = әле оригиналда калган экспортлар
rust-anything app lift .
```
- `app front-door` репозиторийда `main` һәм сервер булмаганда ачык API'ны (һәр берәмлекнең экспортларын) таба
(башка очракта `--library`) һәм `rust/app`ны китапханә crate'ы итеп ясый. Һәр тоташтырылган
берәмлек аның модуле була: `pub use textkit_rs::port as textkit;`.
- `app wire` `bridge` ясаган crate'ны ала, `gate` җибәрә һәм берәмлекнең shadow drop-in'ын яза:
оригинал пакет аны берәмлек урынына импортлый, шуңа күрә аны чакыручылар оригинал API'ны саклый һәм
Rust'ка барып җитә. `RUST_ANYTHING_UNIT_=original` берәмлекне кире җибәрә (C: shadow флагларыннан башка
җыегыз).
- `app replay` һәр тоташтырылган берәмлекнең язып алынган очракларын аның bindings'ы аша җибәрә. Fallback өлеше
ул Rust әле җавап бирмәгән ачык экспортлар өлеше: тоташтырылмаган берәмлекләр һәм `bridge` оригинал телдә
калдырган экспортлар.
- `app lift` өчен 0 fallback һәм `gate` узган һәр берәмлек кирәк; ул берәмлекләрдән bindings, wrapper'лар һәм
shadow'ларны алып ташлый һәм `rust/app`ны бер саф Rust китапханәсе итеп калдыра. Ул бер генә
`port.rs`ка да кагылмый, шуңа күрә bindings аша туры килгән очраклар аны әле дә тасвирлый; чеклист
shadow'ларны әле дә импортлаучы оригинал файллар турында кисәтә.
Бу бишесе дә MCP кораллары: `app_record`, `app_replay`, `app_front_door`, `app_wire` һәм
`app_lift`.
## Мисал: x18n үзәге
x18n үзәгенең API'ны үзгәртмичә күчереп була торган барлык 29 функциясе rust-anything белән күчерелде:
һәр gate уза һәм язып алынган 7 925 очрак төгәл туры килә. Аннары `rust-anything bench` портларның
JS'тан чакырганда TS'тан әкренрәк икәнен күрсәтте, чөнки 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) // һәр төймә басылганда: индекслар, иң яхшысы беренче
```
`port.rs` эчендәге `FuzzyScoreIndex` структурасы стандарт циклны элементларны бер тапкыр әзерләүче
цикл белән алыштыра һәм үзе ранжирлый ала (`rank`): ул ачкычларны кечкенә хәрефләрдә, һәрберсенә символ маскасы белән,
һәр ачкычта һәр киң таралган символның беренче позициясе таблицасын (бер хәрефле сорау бер
багана була) һәм соңгы сорауның туры килүләрен саклый (`s` артыннан `se` язу бары тик `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 |
| `FuzzyScoreIndex` белән `FuzzyScoreBatch` (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 белән бүлеп бирә: система аллокаторы белән Go batch бер агымнан
әкренрәк иде. Демо: [`demo/x18n-search`](../demo/x18n-search/README.md).
## Алты телдә чын код
Go'ның `path`, Ruby'ның `shellwords`, Python'ның `colorsys`, кечкенә фасадлар артындагы JDK һәм glibc
тәртибе: һәр порт үзенең gate'ын уза, барлыгы 13 010 язып алынган очрак. Бу җибәрүләр rust-anything эчендә
хаталар тапты һәм төзәтте (`serde_json` аша бер ULP'ка аерылган float'лар, язып алу вакытында C егылулары,
типсыз кодның чүп кертмәләр алуы). Һәр функция өчен чакырганда Ruby порты Ruby'дан 4,4x тизрәк,
ә Python порты CPython'нан 1,35x тизрәк эшли, ә Go һәм Java'ның яфрак функцияләре
үз телләрендә тизрәк кала; batch буларак барысы да ота (өстәге таблицаны карагыз).
Хисап: [`docs/real-world-languages.md`](./real-world-languages.md).
## Мисал: x18n эченнән чын модуль
[x18n](https://github.com/x18n-dev/x18n) проектыннан `packages/core/src/fuzzy.ts`, ике юл белән дә
[`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}
```
JS `indexOf` 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` оригиналны аның үз runtime'ында җибәрә: TS өчен Node 22.6+ (ул `.ts`
чыганакларын туры җибәрә), Python һәм C өчен Python 3.9+ (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
модуле оригиналны re-export итә. TS өчен:
функцияләр алучы яки кайтаручы функцияләр, генераторлар һәм итераторлар, RegExp, `instanceof` тикшерүләре,
generics һәм типлары (импортлар, re-export'лар һәм `extends` аша кузәтеп) функцияләр
тотучы кыйммәтләр. `--keep "name: reason"` күбрәк калдыра, мәсәлән `Intl` мәгълүматларына бәйле код.
- TS типлары Rust типларына туры китерелә, type alias'лар импортлар аша чишелә, ә параметр типлары
алдан билгеләнгән кыйммәтләрдән чыгарыла; структуралы кыйммәтләр ясалган бинар wire формат аша күчә (JSON бары тик
wire формат модельләштермәгән формалар өчен запас вариант буларак).
- JSON `undefined`, NaN, Infinity, -0 яки ялгыз сурогатларны белдерә алмый: структуралы кыйммәтләр
билгеләр йөртә (`{"$undefined": true}`, `{"$num": "NaN"}`, `{"$utf16": [...]}`), аларны ясалган
`index.cjs` тәрҗемә итә, ярдәмчеләр crate'ның `js.rs` файлында.
`record` TS чыганакларын булганча җибәрә: Node resolve hook бандлер стилендәге импортларны кузәтә
(`./errors` импорты `./errors.ts` файлына), репозиторийда урнаштырылган npm пакетлары булмаса, `--resolve-from` аларны бирә,
ә үзгәртүне таләп иткән TS (enum'нар, parameter properties)
`--experimental-transform-types` белән кабат җибәрелә.
## `analyze` нәрсәгә карый
- Пакетлар (`package.json`) һәм чыганак файллар; `node_modules`, җыю нәтиҗәләрен, fixtures,
playground'ларны, корал конфигурацияләрен төшереп калдыра. Vue/Svelte/Astro `