Le crabe rust-anything, dont la bouche est une balise de code

rust-anything

par erKam Yaman

English · Türkçe · 简体中文 · 繁體中文 · Deutsch · Français · Русский · Українська · 日本語 · 한국어 · Azərbaycanca · Oʻzbekcha · Қазақша · Кыргызча · Türkmençe · Татарча · ئۇيغۇرچە · Português

Cette traduction est maintenue par la communauté et peut être en retard sur le README anglais.

Réécrivez toute votre application en Rust. Gardez-la fonctionnelle tout du long.

CLI, serveurs et bibliothèques, morceau par morceau, vérifiés par rapport à l'original à chaque étape.

Node.js et TypeScript · Python · C · Go · Ruby · Java · PHP et C# en aperçu

version crates.io version npm 6 langages Fonctionne avec 4 agents Tests Licence MIT Étoiles GitHub

jusqu'à 20x plus rapide · 38 251 cas enregistrés rejoués · 0 divergence · une seule commande

Saisie de user.profile dans la recherche de x18n sur 50 000 clés : TypeScript met 143 ms, le traitement par lots rust-anything met 6,9 ms, avec les mêmes résultats à chaque frappe.

**Réécrivez toute votre application en Rust, un morceau à la fois.** rust-anything enregistre ce que fait aujourd'hui votre application Node.js (TypeScript/JavaScript), Python, C, Go, Ruby ou Java, puis vérifie chaque morceau de la réécriture Rust par rapport à cet enregistrement avant de passer à la suite, jusqu'à ce que l'application soit entièrement en Rust. CLI, serveurs HTTP et bibliothèques ; votre agent de programmation (ou vous) écrit le code Rust. Il ne peut détecter que ce que l'enregistrement couvre : voir [Ce qui lui échappe](#ce-qui-lui-échappe). Vous voulez seulement accélérer la partie lente ? Ne portez que celle-ci, un chemin chaud à la fois : | Charge réelle, mêmes résultats que l'original | Original | Avec rust-anything | | --- | ---: | ---: | | Recherche dans la barre latérale de x18n, 50 000 clés (TypeScript, Node) | 10 ms par requête | **0,5 ms : 20x plus rapide** | | La même recherche dans le navigateur (wasm, un thread) | 10 ms | **0,95 ms : 11,5x** | | `slugify` sur 20 000 chaînes (Python) | 98 ms | **17x plus rapide** | | `Shellwords.shellescape` de la bibliothèque standard Ruby, 50 000 valeurs | 88 ms | **11,8x plus rapide** | | `Slugify` sur 50 000 chaînes (Go) | 49 ms | **4x plus rapide** | | `slugify` sur 50 000 chaînes (Java) | 43 ms | **3x plus rapide** | Mesuré sur 4 cœurs ; chaque chiffre dispose d'un benchmark dans [`demo/`](../demo) qui vérifie d'abord que les résultats sont identiques. Appeler Rust une fois par petite fonction est généralement *plus lent* qu'un JIT ; rust-anything identifie la boucle qui vaut la peine d'être déplacée, et la déplace. > rust-anything est un projet indépendant, qui n'est ni affilié au Rust Project ou à la Rust Foundation, > ni approuvé par eux. « Rust » est une marque déposée de la Rust Foundation. ## Démarrage rapide Collez ceci dans Claude Code, Codex, Cursor ou Gemini CLI et laissez votre agent l'installer : ```text Installe rust-anything : exécute `cargo install rust-anything`, puis `rust-anything setup`. Dis-moi quand je dois te redémarrer. ``` Ou faites-le vous-même : ```sh cargo install rust-anything # depuis crates.io rust-anything setup # l'enregistre auprès de Claude Code, Codex, Cursor et Gemini CLI ``` Pas encore de chaîne d'outils Rust ? Des binaires précompilés pour macOS, Linux et Windows sont joints à chaque [release GitHub](https://github.com/erkamyaman/rust-anything/releases), et pour les projets JavaScript, `npm install -g rust-anything` installe le même binaire. Dans Claude Code, vous pouvez aussi l'installer en tant que plugin (le serveur MCP et le skill ; le CLI ci-dessus doit se trouver dans votre `PATH`) : ```text /plugin install rust-anything --marketplace erkamyaman/rust-anything ``` `setup` ajoute le serveur MCP à chaque agent détecté et installe le skill de workflow là où l'agent lit ses skills. Il conserve vos autres paramètres, peut être relancé sans risque, et `--remove` supprime les entrées configurées (sans restaurer les anciennes valeurs éventuellement mises à jour par `setup`). Demandez ensuite à votre agent, par exemple : - *« Réécris ce CLI en Rust avec rust-anything, de bout en bout, et prouve qu'il se comporte à l'identique. »* - *« Cette recherche semble lente. Profile-la avec rust-anything et déplace la boucle critique vers Rust. »* - *« Planifie une migration de `src/parser/` vers Rust avec rust-anything ; porte la première unité et prouve-la. »* - *« Compare les performances du portage Rust dans `rust/text-rs` face à l'original et dis-moi s'il faut le livrer. »* ### Fonctionne avec | Agent | Ce que `rust-anything setup` ajoute | | --- | --- | | Claude Code | Serveur MCP dans `~/.claude.json`, skill dans `~/.claude/skills/` | | Codex | Serveur MCP dans `~/.codex/config.toml`, skill dans `~/.codex/skills/` | | Cursor | Serveur MCP dans `~/.cursor/mcp.json` | | Gemini CLI | Serveur MCP dans `~/.gemini/settings.json` | | Tout autre client MCP | ajouter `rust-anything mcp` manuellement comme serveur stdio (voir [Installation](#installation)) | Avant de modifier un fichier existant, `setup` en enregistre une copie à côté (`.rust-anything.bak`). Ou exécutez les étapes vous-même :

rust-anything profile repère fuzzyScore dans une boucle, bridge --batch génère la crate Rust, gate passe avec 2000/2000 cas enregistrés, et le benchmark affiche 20,7x plus rapide que TS.

```sh rust-anything profile . -- node bench.mjs # ce qui consomme du temps, et qui l'appelle rust-anything bridge . src/fuzzy.ts --batch fuzzyScore:text # écrivez src/port.rs (ou laissez votre agent le faire), puis : rust-anything record rust/fuzzy-rs && rust-anything build rust/fuzzy-rs rust-anything diff rust/fuzzy-rs # chaque cas enregistré doit correspondre rust-anything bench rust/fuzzy-rs # plus rapide ? le verdict tranche rust-anything gate rust/fuzzy-rs # terminé signifie que ce contrôle passe ``` rust-anything ne traduit pas le code automatiquement : votre agent de programmation (Claude Code, Codex, Cursor, ...) ou vous-même écrivez le Rust. rust-anything fournit ce qu'un agent ne peut pas deviner de manière fiable : où passe le temps, quoi porter en premier et dans quel ordre, un pont pour que le reste du code appelle le Rust sans changer son API, le comportement exact que le portage doit reproduire, un moyen sûr de le déployer et un contrôle final indiquant quand un portage est terminé. ## Langages | Langage | Unité | Pont | Enregistré et rejoué par | | --- | --- | --- | --- | | TypeScript/JavaScript | dossier ou fichier | napi-rs ou wasm-bindgen avec un protocole binaire généré ; classes et asynchrone inclus | Node, en exécutant les sources `.ts` | | Python | paquet ou module | PyO3 (abi3), conversion directe, exceptions typées | Python, en important l'original | | C | fichier `.c` | fonctions `extern "C"` portant les noms d'origine et un fichier d'en-tête | l'original compilé en bibliothèque partagée, appelé via ctypes, un fork par cas | | Go | paquet | appels cgo typés et protocole binaire généré, dans un paquet conservant l'API d'origine | un pilote Go généré, compilé comme son propre module | | Ruby | fichier ou dossier de fonctions de module | une extension magnus sous les modules d'origine | un pilote Ruby généré | | Java | paquet de méthodes `public static` | JNI typé et protocole binaire généré, dans des classes enveloppes conservant les méthodes d'origine | un pilote par réflexion généré | | PHP (aperçu) | dossier de fonctions et de méthodes `public static` | à venir : PHP FFI sur une ABI C | applications complètes dès aujourd'hui : `app record`, `app replay` et la porte d'entrée, pour les CLI et les serveurs (`php -S`) | | C# (aperçu) | dossier de méthodes `public static` | à venir : P/Invoke sur une ABI C | applications complètes dès aujourd'hui : `app record`, `app replay` et la porte d'entrée, pour les CLI et les serveurs ASP.NET (`dotnet .dll`) | Chaque langage sauf C obtient également des classes de traitement par lots (`--batch`) : les éléments traversent la frontière une seule fois et restent en Rust, et chaque appel s'exécute sur l'ensemble des éléments sur tous les cœurs. Le langage est détecté à partir du dépôt (`go.mod`, `pom.xml`, un `.csproj` ou `.sln`, `pyproject.toml`, `Gemfile`, `composer.json`, `package.json`, sinon les fichiers sources les plus courants) ; `--lang` permet de le forcer. Les types proviennent des sources : types TS, annotations Python, signatures C, Go, Java et C#, balises Ruby YARD, types PHP et phpdoc ; les paramètres non typés utilisés comme des nombres sont inférés comme nombres. PHP est en aperçu : `analyze` planifie une application PHP (paquets Composer et chargement automatique PSR-4, risques tels que la comparaison souple et le débordement d'entiers en flottants, paquets Composer mappés vers des crates), et un CLI ou serveur PHP peut être enregistré, rejoué et placé derrière une porte d'entrée Rust. Le portage de ses unités en Rust via la FFI de PHP est l'étape suivante ([issue #2](https://github.com/erkamyaman/rust-anything/issues/2)). C# est en aperçu de la même manière : `analyze` lit les projets `.csproj` et leurs paquets NuGet (mappés vers des crates), résout les directives `using` vers les dossiers correspondants et signale ce que C# gère différemment (`decimal`, `dynamic`, requêtes différées LINQ, `Task`, `lock`, réflexion). Un CLI C# ou un serveur ASP.NET peut être enregistré, rejoué et placé derrière une porte d'entrée Rust ; le portage d'unités via P/Invoke viendra ensuite. ## Fonctionnement ``` profile ──> analyze ──> bridge ──> record ──> port.rs ──> diff ──> bench ──> shadow ──> gate où passe quoi la crate ce que vous ou chaque plus les deux terminé si le temps porter Rust et l'original votre cas rapide ? côte à ce contrôle d'abord l'enveloppe fait agent testé le côte en passe l'écrit verdict production ``` L'original reste la source de vérité : `record` l'exécute sur des cas limites (et sur vos propres entrées) et sauvegarde ce qu'il retourne ou lève ; `diff` rejoue chaque cas sur le Rust ; rien n'est livré tant que tout ne correspond pas et que `gate` ne passe pas. Les appelants conservent l'API d'origine tout du long. Une application entière suit la même boucle unité par unité, à l'intérieur d'un cadre qui prouve le programme complet ([Porter toute une application](#porter-toute-une-application)) : ``` analyze --whole-app ──> app record ──> app front-door ──> par unité : la boucle ci-dessus, puis app wire ──> app lift forme, chaque ce que Rust détient le gate passe, donc l'unité répond en pur Rust, dépendance, les l'app fait point d'entrée ; Rust : rejeu à 100 %, taux de repli prouvé par décisions à prendre de l'extérieur l'original répond en baisse le rejeu ``` ## La boucle | Étape | Commande | Ce qu'elle fait | | --- | --- | --- | | 0. Profilage | `rust-anything profile -- node bench.mjs` | Exécute une charge réelle sous le profileur du langage (node, cProfile, `go test` pprof, JFR, un traceur Ruby) : fonctions chaudes par temps inclusif, leurs appelants, et quelles boucles traiter par lots ; signale le code déjà compilé (numba, Cython, JAX), où Rust apporte peu | | 1. Planification | `rust-anything analyze ` | Unités, ordre de portage, risques avec `file:line`, pont par unité, correspondance dépendance-crate, meilleurs premiers portages ; `--whole-app` ajoute les points d'entrée et la forme, chaque dépendance (importée ou déclarée) avec sa crate, les blocs (les unités qui s'importent mutuellement bougent ensemble) et des décisions numérotées avec une réponse recommandée | | 2. Pont | `rust-anything bridge ` | Crate contenant les liaisons (`lib.rs`, plus l'enveloppe chargée par le langage source) et les ébauches à porter (`port.rs`) ; `--batch fn:param` ajoute une classe qui conserve de nombreuses valeurs `param` en Rust | | 3. Enregistrement | `rust-anything record ` | Exécute l'original sur des cas limites générés (non-ASCII, emoji, `-0`, `NaN`, entiers là où des flottants sont attendus, ...) et sur chaque piège sémantique de chaque paramètre (longueur et casse de chaîne, division signée, bords de débordement, affichage des flottants, ordre des maps et tris), et enregistre `cases.jsonl` ; `--float-tolerance 1e-9` autorise une marge relative sur les flottants pour le code numérique | | 3. Compilation | `rust-anything build ` | Compile la partie Rust : `.node`, paquet wasm, extension Python ou bibliothèque partagée | | 3. Comparaison | `rust-anything diff ` | Rejoue les cas enregistrés sur le Rust, appelé exactement comme le font les appelants de l'original ; liste les divergences | | 3. Benchmark | `rust-anything bench ` | Chronomètre les cas enregistrés sur l'original et sur le Rust, pont inclus | | 4. Mode shadow | `rust-anything shadow ` | Remplacement transparent qui exécute les deux, retourne le résultat de l'original et signale les divergences ; `RUST_ANYTHING_MODE=old\|shadow\|new` | | 5. Contrôle | `rust-anything gate ` | fmt, clippy `-D warnings`, tests, audit `unsafe`, rien de non porté, un cas d'échec enregistré pour chaque chemin d'erreur de l'original, aucun `unwrap`/`expect`/`panic!` là où l'original renvoie une erreur (sauf mention `// INFALLIBLE: `), compilation, API, comportement | | Agents | `rust-anything setup` | Enregistre le serveur MCP (`rust-anything mcp`, chaque étape exposée comme outil) et le skill de workflow ([`skills/rust-anything/SKILL.md`](../skills/rust-anything/SKILL.md)) auprès de vos agents de programmation | ## Porter toute une application L'objectif est une application en pur Rust qui se comporte comme l'original, tout en conservant l'original comme référence. Votre agent écrit le Rust ; rust-anything ordonne le travail, génère l'ossature et prouve chaque étape. Le [skill pour application complète](../skills/rust-anything/whole-app.md) guide l'agent tout au long du processus, en commençant par les décisions que vous seul pouvez prendre : - **Cadrage (Grilling)** : l'agent pose des questions par séries, chaque question accompagnée de sa réponse recommandée, jusqu'à ce que toutes les décisions dont dépend le portage soient tranchées, et consigne chacune sous forme d'ADR dans `rust/DECISIONS.md`, avec `rust/GLOSSARY.md` associant les termes de l'original aux noms Rust. - **Recherche** : des agents en arrière-plan lisent les sources primaires de chaque dépendance et rédigent `rust/research/.md`, avec chaque piège sémantique identifié. - **D'une session à l'autre** : `rust/MAP.md` liste chaque unité avec son état ; une session revendique une unité avant de démarrer, et chaque point de contrôle laisse un fichier `rust/HANDOFF.md` pour la session suivante. Les unités d'une même vague peuvent être portées en parallèle par des sous-agents. - **Bascule (Cutover)** : l'agent fait ce qu'il peut et écrit `rust/cutover.sh`, un script interactif pour les étapes que vous seul pouvez effectuer (déploiements, DNS, secrets), avec un retour arrière possible à chaque étape. Le cadrage, la recherche et ces pratiques sont adaptés des [skills de Matt Pocock](https://github.com/mattpocock/skills). Planifiez d'abord : `rust-anything analyze . --whole-app` ajoute la forme de l'application (CLI, serveur ou bibliothèque) et les points d'entrée, chaque dépendance externe (importée ou déclarée) avec sa crate Rust et son adéquation, l'ordre de portage sous forme de blocs (les unités qui s'importent mutuellement bougent ensemble), et des décisions numérotées avec une réponse recommandée : unités à conserver, unités bloquées, dépendances sans crate ou avec une crate partielle. Prouvez ensuite le programme entier de l'extérieur. `record` et `diff` prouvent une unité ; `app record` et `app replay` prouvent l'application, pour les CLI et serveurs dans n'importe lequel des six langages (l'application est une boîte noire) : ```sh rust-anything app record . -- python3 cli.py # la commande qui lance l'original rust-anything app replay . # l'original doit passer à 100 % rust-anything app replay . --build "target/release/mytool" ``` - `app record` exécute l'original sur les exemples documentés de l'application elle-même (lignes `$ mytool ...` dans ses fichiers Markdown et shell, avec les fichiers qu'ils nomment), un fichier JSONL `--inputs` (`{"name", "args", "stdin", "env", "files"}`), et des pièges sémantiques dérivés de ces cas (chaînes non-ASCII et emoji, division et modulo négatifs, débordement, flottants très grands ou très petits, ordre des maps, fichiers manquants). Chaque cas s'exécute deux fois ; ce qui diffère entre les deux exécutions devient un joker `[..]`. `--normalize timestamps|uuids|key-order` ou `--normalize name=regex` ajoute des normaliseurs, enregistrés avec les cas. - Les cas sont des fichiers [trycmd](https://docs.rs/trycmd) dans `rust/app-cases/` : `.toml` (argv, env, code de sortie), `.stdin`, `.stdout`, `.stderr`, `.in/` (fichiers en entrée) et `.out/` (fichiers écrits). Lisez-les et modifiez-les à la main ; un test Rust peut les exécuter avec `trycmd` dès que le portage dispose d'un binaire. - `app replay` exécute n'importe quel binaire compilé sur ces cas, affiche `passed/total`, écrit `rust/app-cases/replay-report.md` avec un diff par cas en échec, et quitte avec un code non nul au moindre écart. Un binaire qui ajoute des lignes au fichier indiqué par `RUST_ANYTHING_FALLBACK_LOG` (une ligne par repli vers l'original), comme le fait la porte d'entrée ci-dessous, voit également son taux de repli rapporté. - `app replay --case ` relance un seul cas à partir du nom indiqué dans le rapport : une boucle rapide et reproductible pour corriger une divergence avant de tout relancer. Déplacez ensuite le point d'entrée vers Rust et confiez-lui les commandes une unité à la fois : ```sh rust-anything app front-door . # rust/app : chaque commande exécute l'original rust-anything app wire . textkit --command upper # une fois que textkit-rs passe gate # écrivez le code de liaison dans rust/app/src/units/textkit.rs, puis : rust-anything app wire . textkit # à nouveau 100 %, taux de repli plus bas ``` - `app front-door` génère `rust/app`, un binaire Rust portant le nom de l'application : un analyseur clap pour les commandes et options des cas enregistrés, où chaque commande exécute l'original avec les mêmes argv, stdin et environnement et transmet sa sortie et son code de sortie. Chaque repli est compté, si bien que rejouer la porte d'entrée fraîchement générée donne 100 % de réussite pour 100 % de repli (elle se compile et se rejoue pour le démontrer). Elle n'écrase jamais `rust/app` : le code vous appartient dès lors. - `app wire --command ` exécute `gate` sur la crate de l'unité (`--skip-gate` s'il vient de passer), l'ajoute à `rust/app` comme bibliothèque, génère une fois `src/units/.rs` pour que vous ou votre agent le remplissiez (analyser les arguments, appeler `::port`, afficher ce que l'original affiche), y dirige les commandes, puis recompile et rejoue. `RUST_ANYTHING_UNIT_=original` renvoie une unité raccordée vers l'original jusqu'à la bascule finale. Raccordez le nom même de l'application comme commande (`--command mytool`) pour les appels sans nom de commande : sans argument, commandes inconnues, erreurs d'usage. Lorsque le rejeu passe avec un taux de repli de 0 et que chaque unité passe `gate`, transformez-la en une application pur Rust : ```sh rust-anything app lift . ``` - `app lift` refuse tant que les deux conditions ne sont pas réunies, et indique ce qui bloque : les cas qui se replient encore sur l'original, les codes de liaison encore à l'état d'ébauche, les unités qui échouent à `gate`. - Sur une copie d'abord, il supprime le chemin de repli et les interrupteurs d'urgence, transforme chaque crate d'unité en une simple bibliothèque de `rust/app` (sans `cdylib`, liaisons ni enveloppes générées), et ajoute `rust/app/tests/app_cases.rs`, qui exécute `rust/app-cases` avec trycmd lors de `cargo test`, de sorte que la CI n'a besoin que de cargo. - Puis il exécute la liste de vérification finale : fmt, clippy `-D warnings` et tests sur chaque unité et sur `rust/app`, compilation ou vérification de chaque cible nommée dans `rust/DECISIONS.md` lorsqu'elle est installée, fichiers lus à l'exécution et dossiers de ressources non embarqués, et rejeu sur le binaire pur. Ce n'est que lorsque tout passe que les modifications sont réécrites. L'original n'est jamais touché. ### Serveurs Les mêmes commandes prouvent les serveurs HTTP. `--http` indique que la commande démarre un serveur ; il récupère son port depuis `PORT` ou `{port}` dans la commande (`--port` pour un serveur qui écoute toujours sur le même port) : ```sh rust-anything app record . --http -- node server.js rust-anything app replay . rust-anything app front-door . # axum : chaque route est relayée par proxy rust-anything app wire . api --route 'GET /users/{id}' --route '*' rust-anything app lift . ``` - Les requêtes proviennent des lignes `curl` dans la documentation de l'application (`curl -X POST -d ... http://localhost:8080/x`), de `--inputs` (`{"name", "method", "path", "headers", "body"}`) et de pièges : segments de chemin et paramètres de requête remplacés par les mêmes pièges que les arguments CLI, corps de requêtes remplacés par des pièges texte et JSON, et une route inconnue. Chaque exécution redémarre le serveur à neuf et envoie les requêtes par ordre de nom, de sorte que l'état entre requêtes est conservé. - Les cas sont `rust/app-cases/http/.toml` (la requête, le statut et les en-têtes qui comptent) et `.body` (le corps de réponse, avec `[..]` là où deux exécutions ont différé). Date, serveur et autres en-têtes propres à chaque réponse sont omis ; supprimez toute ligne d'en-tête qui ne vous intéresse pas. - La porte d'entrée est un serveur axum qui lance l'original sur son propre port et relaie par proxy chaque route qu'aucune unité ne traite. `wire --route` accepte les routes axum : `METHOD /path/{param}`, `/path` pour n'importe quelle méthode, `*` pour tout le reste ; le code de liaison reçoit la route, ses paramètres et la requête. `lift` supprime le proxy ; les cas HTTP s'exécutent alors en CI avec `app replay`. ### Bibliothèques Une bibliothèque n'a pas de processus à rejouer : son API publique est la porte d'entrée, et les cas enregistrés de chaque unité constituent la preuve. ```sh rust-anything app front-door . # rust/app : une crate Rust avec l'API publique # chaque unité suit la boucle : bridge, record, port.rs, build, diff, gate ; puis : rust-anything app wire . textkit-rs # réexportée depuis rust/app ; l'original importe son module shadow rust-anything app replay . # les cas de chaque unité raccordée ; repli = exports encore dans l'original rust-anything app lift . ``` - `app front-door` détecte l'API publique (les exports de chaque unité) lorsque le dépôt n'a ni `main` ni serveur (`--library` sinon), et génère `rust/app` en tant que crate de bibliothèque. Chaque unité raccordée en devient un module : `pub use textkit_rs::port as textkit;`. - `app wire` prend une crate créée par `bridge`, exécute `gate`, et écrit le module de remplacement shadow de l'unité : le paquet d'origine l'importe à la place de l'unité, si bien que ses appelants conservent l'API d'origine et atteignent le Rust. `RUST_ANYTHING_UNIT_=original` renvoie l'unité vers l'original (C : compilez sans les options du shadow). - `app replay` exécute les cas enregistrés de chaque unité raccordée à travers ses liaisons. Le taux de repli est la part des exports publics auxquels Rust ne répond pas encore : unités non raccordées, et exports que `bridge` garde dans le langage d'origine. - `app lift` exige un repli à 0 et que chaque unité passe `gate` ; il retire les liaisons, enveloppes et modules shadow des unités et laisse `rust/app` comme une seule bibliothèque pur Rust. Il ne touche à aucun `port.rs`, donc les cas qui correspondaient via les liaisons la décrivent toujours ; la vérification signale les fichiers de l'original qui importent encore les modules shadow. Les cinq sont aussi des outils MCP : `app_record`, `app_replay`, `app_front_door`, `app_wire` et `app_lift`. ## Étude de cas : le cœur de x18n Les 29 fonctions du cœur de x18n qui peuvent être déplacées sans changement d'API ont toutes été portées avec rust-anything : chaque `gate` passe et 7 925 cas enregistrés correspondent exactement. `rust-anything bench` a ensuite montré que les portages sont plus lents que le TS appelé depuis JS, car le pont coûte plus cher que le travail effectué. Rapport complet : [`demo/x18n-core`](../demo/x18n-core/README.md). La leçon est intégrée à l'outil : mesurez avec `bench` avant de livrer un portage. ## Chemins chauds : garder les données en Rust Un portage appelé une fois par élément paie le coût du pont à chaque élément, et perd face à un JIT. Ce qui gagne, c'est de déplacer la boucle : `profile` la trouve, et `--batch` génère une classe qui prend les éléments une fois et exécute la fonction sur tous en un seul appel, sur tous les cœurs, avec des résultats en tableaux typés. ```sh rust-anything profile ../x18n -- node --experimental-strip-types $PWD/demo/x18n-search/search.ts . # -> fuzzyScore : un quart de l'exécution, appelé par clé par `matched` : passez-le en lot rust-anything bridge ../x18n packages/core/src/fuzzy.ts --batch fuzzyScore:text ``` ```js const search = new FuzzyScoreBatch(keys) // une seule fois const order = search.rank(query, 0) // à chaque frappe : indices, les meilleurs d'abord ``` Une structure `FuzzyScoreIndex` dans `port.rs` remplace la boucle par défaut par une implémentation qui prépare les éléments une fois, et peut classer directement (`rank`) : elle conserve les clés en minuscules avec un masque de caractères pour chacune, une table de la première position de chaque caractère courant dans chaque clé (une requête d'une lettre ne lit qu'une colonne), et les correspondances de la dernière requête (taper `se` après `s` ne recalcule le score que sur ce que `s` a trouvé). Sur la recherche de la barre latérale de x18n sur 50 000 clés, tapées lettre par lettre, avec des résultats identiques : | | Par requête | vs TS | | --- | ---: | ---: | | TS : `map(fuzzyScore)`, filtre, tri | 10 ms | 1x | | TS avec le même filtrage progressif que l'index | 4,1-5,4 ms | 2x | | Le même portage, appelé par clé | - | 0,2-0,4x | | `FuzzyScoreBatch`, index par défaut (4 cœurs) | 5,1 ms | 1,7x | | `FuzzyScoreBatch` avec `FuzzyScoreIndex` (napi, 4 cœurs) | 0,45-0,56 ms | **18-22x** | | Le même avec wasm (un thread) | 0,95 ms | **11,5x** | Face au TS effectuant le même filtrage progressif, Rust reste 7 à 12x plus rapide (wasm 5x). Convertissez les indices retournés en clés avec une simple boucle : `Array.from(order, i => keys[i])` coûtait 20x plus cher, 0,4 ms. Chaque langage dispose de traitements par lots, et ils battent l'original même là où les portages appelés unité par unité perdent. Le même travail sur 4 cœurs, résultats et erreurs identiques (benchmarks dans chaque dossier demo) : | Langage | Charge de travail | Original | Portage par appel vs original | Lot vs original | | --- | --- | ---: | ---: | ---: | | TS | recherche x18n, 50 000 clés | 10 ms | 0,2-0,4x | **20x** | | Python | `slugify`, 20 000 chaînes | 98 ms | - | **17x** | | Ruby | `slugify`, 20 000 chaînes | 110 ms | - | **12,7x** | | Ruby | `shellescape` (stdlib), 50 000 valeurs mixtes | 88 ms | - | **11,8x** | | Go | `Slugify`, 50 000 chaînes | 49 ms | 0,93x | **4x** | | Java | `slugify`, 50 000 chaînes | 43 ms | 0,68x | **3x** | Les langages compilés d'origine gagnent moins : le travail par élément est déjà rapide, donc le traitement par lots gagne grâce au nombre de cœurs. Les crates de lots allouent avec mimalloc : avec l'allocateur système, le lot Go était plus lent qu'un seul thread. Démo : [`demo/x18n-search`](../demo/x18n-search/README.md). ## Du code réel dans six langages `path` de Go, `shellwords` de Ruby, `colorsys` de Python, ainsi que des comportements du JDK et de la glibc derrière de petites façades : chaque portage passe son contrôle `gate`, 13 010 cas enregistrés au total. Ces exécutions ont révélé et corrigé des bogues dans rust-anything (flottants décalés d'un ULP via `serde_json`, plantages en C pendant l'enregistrement, code non typé recevant des entrées invalides). Appelé par fonction, le portage Ruby tourne 4,4x plus vite que Ruby et le portage Python 1,35x plus vite que CPython, tandis que les fonctions feuilles Go et Java restent plus rapides dans leur propre langage ; en lots, tous gagnent (voir le tableau ci-dessus). Rapport : [`docs/real-world-languages.md`](./real-world-languages.md). ## Exemple : un vrai module de x18n `packages/core/src/fuzzy.ts` de [x18n](https://github.com/x18n-dev/x18n), porté des deux façons dans [`demo/`](../demo) : ```sh rust-anything analyze ../x18n # fuzzy.ts : prêt, wasm-bindgen (core tourne dans les navigateurs) rust-anything bridge ../x18n packages/core/src/fuzzy.ts --out demo/fuzzy-rs rust-anything record demo/fuzzy-rs --count 2000 # écrivez src/port.rs rust-anything gate demo/fuzzy-rs ``` Un premier portage qui indexait par `char` Rust passait des tests simples mais échouait à `diff` : ``` 198/200 cases match - fuzzyScore("b😀", "a😀b😀c"): expected {"ok":1997}, got {"ok":1998} ``` `indexOf` en JS compte les unités de code UTF-16, donc un emoji compte pour deux positions. Le portage dans `demo/*/src/port.rs` utilise les assistants `utf16` générés et passe 2000/2000 cas ainsi que le contrôle `gate`, en napi-rs (`demo/fuzzy-napi`) comme en wasm-bindgen (`demo/fuzzy-rs`). Le plan généré par rust-anything pour l'ensemble de x18n : [`docs/examples/x18n.md`](./examples/x18n.md). ## Installation ```sh cargo install --path . ``` `record`, `diff` et `bench` exécutent l'original dans son propre environnement d'exécution : Node 22.6+ pour TS (il exécute directement les sources `.ts`), Python 3.9+ pour Python et C (ctypes), Go 1.21+, Ruby 3+, JDK 17+ (`javac` et `java`). C nécessite aussi un compilateur C. Les ponts wasm nécessitent également `rustup target add wasm32-unknown-unknown` et `cargo install wasm-bindgen-cli --version --locked` ; `build` indique la version exacte. Pour les agents, `rust-anything setup` enregistre tout (voir Démarrage rapide). Pour ajouter plutôt manuellement le serveur MCP à un seul projet (`.mcp.json`) : ```json { "mcpServers": { "rust-anything": { "command": "rust-anything", "args": ["mcp"] } } } ``` ## Ce que décide `bridge` - Les exports qui ne peuvent pas traverser un pont restent dans le langage source, avec la raison, et le module shadow réexporte l'original. Pour TS : les fonctions qui prennent ou renvoient des fonctions, les générateurs et itérateurs, RegExp, les vérifications `instanceof`, les génériques, et les valeurs dont les types (suivis à travers les imports, réexports et `extends`) contiennent des fonctions. `--keep "name: reason"` en garde davantage, par ex. du code dépendant des données `Intl`. - Les types TS sont convertis en types Rust, avec résolution des alias de types à travers les imports et inférence des types de paramètres à partir des valeurs par défaut ; les valeurs structurées passent par un protocole binaire généré (JSON uniquement en repli pour les formes que le protocole ne modélise pas). - JSON ne peut pas exprimer `undefined`, NaN, Infinity, -0 ni les substituts isolés (lone surrogates) : les valeurs structurées transportent des marqueurs (`{"$undefined": true}`, `{"$num": "NaN"}`, `{"$utf16": [...]}`) que le fichier généré `index.cjs` traduit, avec des assistants dans `js.rs` de la crate. `record` exécute les sources TS telles quelles : un hook de résolution Node suit les imports de style bundler (`./errors` vers `./errors.ts`), `--resolve-from` fournit les paquets npm lorsque le dépôt n'en a aucun d'installé, et le TS nécessitant une transformation (enums, propriétés de paramètres) est relancé avec `--experimental-transform-types`. ## Ce qu'analyse `analyze` - Les paquets (`package.json`) et fichiers sources ; ignore `node_modules`, les sorties de compilation, les fixtures, les playgrounds, les configurations d'outils. Les blocs `