rust-anything 1.5.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,61 +1,91 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="docs/assets/logo.
|
|
2
|
+
<img src="docs/assets/logo.png" width="160" height="160" alt="The rust-anything crab">
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<h1 align="center">rust-anything</h1>
|
|
6
6
|
|
|
7
|
-
<p align="center">
|
|
7
|
+
<p align="center"><b>Rewrite your app in Rust, and prove it still behaves the same.</b></p>
|
|
8
8
|
|
|
9
|
-
<p align="center">
|
|
10
|
-
|
|
11
|
-
<p align="center"><em>Rewrite your whole app in Rust. Keep it working the whole way.</em></p>
|
|
12
|
-
|
|
13
|
-
<p align="center"><em>CLIs, servers and libraries, piece by piece, checked against the original at every step.</em></p>
|
|
14
|
-
|
|
15
|
-
<p align="center">Node.js and TypeScript · Python · C · Go · Ruby · Java · PHP and C# in preview</p>
|
|
9
|
+
<p align="center">New in 2.0: <a href="docs/real-world.md#prettier">Prettier, ported to Rust</a>. 19x faster · 17,224 recorded runs · 0 mismatches</p>
|
|
16
10
|
|
|
17
11
|
<p align="center">
|
|
18
12
|
<a href="https://crates.io/crates/rust-anything"><img src="https://img.shields.io/crates/v/rust-anything?color=E2862A&label=crates.io" alt="crates.io version"></a>
|
|
19
13
|
<a href="https://www.npmjs.com/package/rust-anything"><img src="https://img.shields.io/npm/v/rust-anything?color=E2862A&label=npm" alt="npm version"></a>
|
|
20
|
-
<img src="https://img.shields.io/badge/languages-6-E2862A" alt="6 languages">
|
|
21
|
-
<a href="#works-with"><img src="https://img.shields.io/badge/works%20with-4%20agents-E2862A" alt="Works with 4 agents"></a>
|
|
22
14
|
<a href="https://github.com/erkamyaman/rust-anything/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/erkamyaman/rust-anything/ci.yml?branch=main&label=tests" alt="Tests"></a>
|
|
23
|
-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-E2862A" alt="MIT license"></a>
|
|
24
15
|
<a href="https://github.com/erkamyaman/rust-anything"><img src="https://img.shields.io/github/stars/erkamyaman/rust-anything?style=social" alt="GitHub stars"></a>
|
|
25
16
|
</p>
|
|
26
17
|
|
|
27
|
-
<p align="center">up to 20x faster · 38,251 recorded cases replayed · 0 mismatches · one command</p>
|
|
28
|
-
|
|
29
18
|
<p align="center">
|
|
30
|
-
<
|
|
19
|
+
<a href="#quick-start">Quick start</a> ·
|
|
20
|
+
<a href="#languages">Languages</a> ·
|
|
21
|
+
<a href="docs/real-world.md">Real-world ports</a> ·
|
|
22
|
+
<a href="docs/how-it-works.md#how-it-works">How it works</a> ·
|
|
23
|
+
<a href="docs/whole-apps.md#port-a-whole-app">Whole apps</a> ·
|
|
24
|
+
<a href="docs/faq.md#faq">FAQ</a>
|
|
31
25
|
</p>
|
|
32
26
|
|
|
27
|
+
<p align="center">Made in Türkiye 🇹🇷 by <a href="https://github.com/erkamyaman">erKam Yaman</a> · <a href="LICENSE">MIT</a></p>
|
|
28
|
+
|
|
29
|
+
<p align="center">Sponsored by <a href="https://coderabbit.ai"><img src="docs/assets/brands/coderabbit.png" width="22" height="22" align="absmiddle" alt=""> <b>CodeRabbit</b></a></p>
|
|
30
|
+
|
|
31
|
+
<p align="center"><sub>English · <a href="docs/README_TR.md">Türkçe</a> · <a href="docs/README_UK.md">Українська</a> · <a href="docs/README_ZH.md">简体中文</a> · <a href="docs/README_ZH-TW.md">繁體中文</a> · <a href="docs/README_DE.md">Deutsch</a> · <a href="docs/README_FR.md">Français</a> · <a href="docs/README_RU.md">Русский</a> · <a href="docs/README_JA.md">日本語</a> · <a href="docs/README_KO.md">한국어</a> · <a href="docs/README_AZ.md">Azərbaycanca</a> · <a href="docs/README_UZ.md">Oʻzbekcha</a> · <a href="docs/README_KK.md">Қазақша</a> · <a href="docs/README_KY.md">Кыргызча</a> · <a href="docs/README_TK.md">Türkmençe</a> · <a href="docs/README_TT.md">Татарча</a> · <a href="docs/README_UG.md">ئۇيغۇرچە</a> · <a href="docs/README_PT.md">Português</a> · <a href="docs/README_VI.md">Tiếng Việt</a></sub></p>
|
|
32
|
+
|
|
33
|
+
<table>
|
|
34
|
+
<tr>
|
|
35
|
+
<td width="25%" valign="top">
|
|
36
|
+
<b>Record</b><br>
|
|
37
|
+
<code>record</code> runs the original on generated edge cases, semantic traps and your own inputs, and saves what it returns or throws.
|
|
38
|
+
</td>
|
|
39
|
+
<td width="25%" valign="top">
|
|
40
|
+
<b>Port</b><br>
|
|
41
|
+
<code>bridge</code> generates the Rust crate and a wrapper, so callers keep the original API. You or your agent write the Rust.
|
|
42
|
+
</td>
|
|
43
|
+
<td width="25%" valign="top">
|
|
44
|
+
<b>Check</b><br>
|
|
45
|
+
<code>diff</code> replays every recorded case against the Rust, and nothing ships until they all match and <code>gate</code> passes.
|
|
46
|
+
</td>
|
|
47
|
+
<td width="25%" valign="top">
|
|
48
|
+
<b>Lift</b><br>
|
|
49
|
+
When replay passes with no fallback and every unit passes gate, <code>app lift</code> makes it a pure Rust app. The original is never touched.
|
|
50
|
+
</td>
|
|
51
|
+
</tr>
|
|
52
|
+
</table>
|
|
53
|
+
|
|
33
54
|
**Rewrite your whole app in Rust, one piece at a time.** rust-anything records what your
|
|
34
55
|
Node.js (TypeScript/JavaScript), Python, C, Go, Ruby or Java app does today, then checks every piece of the
|
|
35
56
|
Rust rewrite against that recording before it moves on, until the app is pure Rust. CLIs, HTTP
|
|
36
57
|
servers and libraries; your coding agent (or you) writes the Rust. It can only catch what the
|
|
37
|
-
recording covers: see [What it can't catch](#what-it-cant-catch).
|
|
38
|
-
|
|
58
|
+
recording covers: see [What it can't catch](docs/how-it-works.md#what-it-cant-catch). Whole tools
|
|
59
|
+
and servers, or only the slow part, one hot path at a time:
|
|
39
60
|
|
|
40
|
-
| Real
|
|
61
|
+
| Real project, same output as the original | Original | With rust-anything |
|
|
41
62
|
| --- | ---: | ---: |
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
63
|
+
| [Prettier](docs/real-world.md#prettier) 3.6.2, 2,360 JS/TS files from the command line | 128.6 s | **6.9 s: 19x faster** |
|
|
64
|
+
| Prettier, 6,305 Markdown files from the command line | 352 s | **22.5 s: 15.6x faster** |
|
|
65
|
+
| [json-server](docs/real-world.md#json-server), a whole Node server: memory at idle | 74 MB | **3.5 MB**, one 5.3 MB binary |
|
|
66
|
+
| json-server, from start to first response | 79 to 85 ms | **8 to 10 ms** |
|
|
67
|
+
| [Fuse.js](docs/real-world.md#fusejs) search over 50,000 strings, per query | 91.2 ms | **2.8 ms: 32x faster** |
|
|
68
|
+
|
|
69
|
+
Prettier: 15,837 of 17,224 recorded runs format fully in Rust across 10 languages (JavaScript,
|
|
70
|
+
TypeScript, JSX, JSON, GraphQL, YAML, Markdown, CSS, SCSS, Less), and all 17,224 match Prettier
|
|
71
|
+
byte for byte, since anything not ported yet falls back to Prettier. json-server: 514/514
|
|
72
|
+
recorded HTTP cases match on a pure Rust binary. Measured on an Apple M4, two runs each, every
|
|
73
|
+
output compared before timing ([details](docs/real-world.md)). Calling Rust once per small
|
|
74
|
+
function is usually *slower* than a JIT; rust-anything finds the loop worth moving, and moves it.
|
|
52
75
|
|
|
53
76
|
> rust-anything is an independent project, not affiliated with or endorsed by the Rust Project
|
|
54
77
|
> or the Rust Foundation. "Rust" is a trademark of the Rust Foundation.
|
|
55
78
|
|
|
79
|
+
> [!WARNING]
|
|
80
|
+
> `record` and `app record` run your original code, calling each function (or the whole app) on
|
|
81
|
+
> many generated inputs, and `app record` runs every case twice. `diff`, `gate` and `app replay`
|
|
82
|
+
> run the same cases again, on the port or the original. Code that writes files, talks to a
|
|
83
|
+
> database or calls the network does that once per case. Run them on a copy of the project, with a
|
|
84
|
+
> test database and no production credentials in the environment.
|
|
85
|
+
|
|
56
86
|
## Quick start
|
|
57
87
|
|
|
58
|
-
Paste this into Claude Code, Codex, Cursor
|
|
88
|
+
Paste this into Claude Code, Codex, Cursor, Gemini CLI or OpenCode and let your agent install it:
|
|
59
89
|
|
|
60
90
|
```text
|
|
61
91
|
Install rust-anything: run `cargo install rust-anything`, then `rust-anything setup`.
|
|
@@ -66,7 +96,7 @@ Or yourself:
|
|
|
66
96
|
|
|
67
97
|
```sh
|
|
68
98
|
cargo install rust-anything # from crates.io
|
|
69
|
-
rust-anything setup # registers it with Claude Code, Codex, Cursor
|
|
99
|
+
rust-anything setup # registers it with Claude Code, Codex, Cursor, Gemini CLI and OpenCode
|
|
70
100
|
```
|
|
71
101
|
|
|
72
102
|
No Rust toolchain yet? Prebuilt binaries for macOS, Linux and Windows are attached to each
|
|
@@ -97,14 +127,31 @@ Then ask your agent, for example:
|
|
|
97
127
|
| Codex | MCP server in `~/.codex/config.toml`, skill in `~/.codex/skills/` |
|
|
98
128
|
| Cursor | MCP server in `~/.cursor/mcp.json` |
|
|
99
129
|
| Gemini CLI | MCP server in `~/.gemini/settings.json` |
|
|
100
|
-
|
|
|
130
|
+
| OpenCode | MCP server in `~/.config/opencode/opencode.json` (`mcp.servers`), skill in `~/.config/opencode/skills/` |
|
|
131
|
+
| Any other MCP client | add `rust-anything mcp` as a stdio server by hand (see [Install](docs/install.md#install)) |
|
|
101
132
|
|
|
102
133
|
Before changing a file that exists, `setup` saves a copy beside it (`<file>.rust-anything.bak`).
|
|
103
134
|
|
|
135
|
+
To wire OpenCode up by hand, put the server in `~/.config/opencode/opencode.json` (`command` is
|
|
136
|
+
the whole argv) and copy [`skills/rust-anything/`](./skills/rust-anything) to
|
|
137
|
+
`~/.config/opencode/skills/rust-anything/`:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"mcp": {
|
|
142
|
+
"servers": {
|
|
143
|
+
"rust-anything": { "type": "local", "command": ["rust-anything", "mcp"] }
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
104
149
|
Or run the steps yourself:
|
|
105
150
|
|
|
106
151
|
<p align="center">
|
|
107
152
|
<img src="docs/assets/terminal.gif" alt="rust-anything profile finds fuzzyScore in a loop, bridge --batch generates the Rust crate, gate passes with 2000/2000 recorded cases, and the benchmark shows 20.7x faster than TS." width="820">
|
|
153
|
+
<br>
|
|
154
|
+
<sub>The steps on x18n's <code>fuzzyScore</code>: <code>profile</code> finds the hot loop, <code>bridge --batch</code> generates the crate, <code>gate</code> passes, and the benchmark compares it with the TypeScript.</sub>
|
|
108
155
|
</p>
|
|
109
156
|
|
|
110
157
|
```sh
|
|
@@ -117,7 +164,7 @@ rust-anything bench rust/fuzzy-rs # faster? the verdict say
|
|
|
117
164
|
rust-anything gate rust/fuzzy-rs # done means this passes
|
|
118
165
|
```
|
|
119
166
|
|
|
120
|
-
rust-anything does not translate code: your coding agent (Claude Code, Codex, Cursor, ...) or you write
|
|
167
|
+
rust-anything does not translate code: your coding agent (Claude Code, Codex, Cursor, OpenCode, ...) or you write
|
|
121
168
|
the Rust. rust-anything supplies what an agent cannot guess reliably: where the time goes, what to port
|
|
122
169
|
first and in which order, a bridge so the rest of the code calls the Rust with its API unchanged,
|
|
123
170
|
the exact behavior the port must match, a safe way to ship it, and a gate that says when a port is
|
|
@@ -133,8 +180,8 @@ done.
|
|
|
133
180
|
| Go | package | typed cgo calls and a generated binary wire, in a package with the original API | a generated Go driver, built as its own module |
|
|
134
181
|
| Ruby | file or folder of module functions | a magnus extension under the original modules | a generated Ruby driver |
|
|
135
182
|
| Java | package of `public static` methods | typed JNI and a generated binary wire, in wrapper classes with the original methods | a generated reflection driver |
|
|
136
|
-
| PHP
|
|
137
|
-
| C#
|
|
183
|
+
| PHP | folder of functions and `public static` methods | coming next: PHP FFI over a C ABI | whole apps today: `app record`, `app replay` and the front door, for CLIs and servers (`php -S`) |
|
|
184
|
+
| C# | folder of `public static` methods | coming next: P/Invoke over a C ABI | whole apps today: `app record`, `app replay` and the front door, for CLIs and ASP.NET servers (`dotnet <app>.dll`) |
|
|
138
185
|
|
|
139
186
|
Every language except C also gets batch classes (`--batch`): the items cross once and stay in
|
|
140
187
|
Rust, and each call runs over all of them on all cores.
|
|
@@ -145,529 +192,54 @@ The language is detected from the repository (`go.mod`, `pom.xml`, a `.csproj` o
|
|
|
145
192
|
signatures, Ruby YARD tags, PHP types and phpdoc; untyped parameters used as numbers are inferred
|
|
146
193
|
as numbers.
|
|
147
194
|
|
|
148
|
-
PHP
|
|
195
|
+
For PHP, `analyze` plans a PHP app (Composer packages and PSR-4 autoloading, risks
|
|
149
196
|
such as loose comparison and integer overflow into floats, Composer packages mapped to crates),
|
|
150
197
|
and a PHP CLI or server can be recorded, replayed and put behind a Rust front door. Porting its
|
|
151
198
|
units into Rust through PHP's FFI is the next step ([issue #2](https://github.com/erkamyaman/rust-anything/issues/2)).
|
|
152
199
|
|
|
153
|
-
C#
|
|
200
|
+
C# works the same way: `analyze` reads `.csproj` projects and their NuGet packages
|
|
154
201
|
(mapped to crates), resolves `using` directives to folders, and flags what C# does differently
|
|
155
202
|
(`decimal`, `dynamic`, LINQ's deferred queries, `Task`, `lock`, reflection). A C# CLI or ASP.NET
|
|
156
203
|
server can be recorded, replayed and put behind a Rust front door; porting units through P/Invoke
|
|
157
204
|
comes next.
|
|
158
205
|
|
|
159
|
-
##
|
|
160
|
-
|
|
161
|
-
```
|
|
162
|
-
profile ──> analyze ──> bridge ──> record ──> port.rs ──> diff ──> bench ──> shadow ──> gate
|
|
163
|
-
where the what to the Rust what the you or every faster? both side done means
|
|
164
|
-
time goes port first crate and original your agent recorded the by side in this passes
|
|
165
|
-
wrapper does write it case verdict production
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
The original stays the source of truth: `record` runs it on edge cases (and your own inputs) and
|
|
169
|
-
saves what it returns or throws; `diff` replays every case against the Rust; nothing ships until
|
|
170
|
-
they all match and `gate` passes. Callers keep the original API throughout.
|
|
171
|
-
|
|
172
|
-
A whole app goes through the same loop unit by unit, inside a frame that proves the whole
|
|
173
|
-
program ([Port a whole app](#port-a-whole-app)):
|
|
174
|
-
|
|
175
|
-
```
|
|
176
|
-
analyze --whole-app ──> app record ──> app front-door ──> per unit: the loop above, then app wire ──> app lift
|
|
177
|
-
shape, every what the app Rust owns the gate passes, so the unit answers in pure Rust,
|
|
178
|
-
dependency, the does from the entry point; the Rust: replay 100%, fallback rate down proved by
|
|
179
|
-
decisions to make outside original answers replay
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
## The loop
|
|
183
|
-
|
|
184
|
-
| Step | Command | What it does |
|
|
185
|
-
| --- | --- | --- |
|
|
186
|
-
| 0. Profile | `rust-anything profile <repo> -- node bench.mjs` | Runs a real workload under the language's profiler (node, cProfile, `go test` pprof, JFR, a Ruby tracer): hot functions by inclusive time, their callers, and which loops to batch; flags code that is already compiled (numba, Cython, JAX), where Rust gains little |
|
|
187
|
-
| 1. Plan | `rust-anything analyze <repo>` | Units, port order, risks with `file:line`, bridge per unit, dependency-to-crate fit, best first ports; `--whole-app` adds entry points and shape, every dependency (imported or declared) with its crate, pieces (units that import each other move together) and numbered decisions with a recommended answer |
|
|
188
|
-
| 2. Bridge | `rust-anything bridge <repo> <unit>` | Crate with the bindings (`lib.rs`, plus the wrapper the source language loads) and stubs to port (`port.rs`); `--batch fn:param` adds a class that keeps many `param` values in Rust |
|
|
189
|
-
| 3. Record | `rust-anything record <crate>` | Runs the original on generated edge cases (non-ASCII, emoji, `-0`, `NaN`, ints where floats are expected, ...) and on every semantic trap in every parameter (string length and case, signed division, overflow edges, float printing, map and sort order), and saves `cases.jsonl`; `--float-tolerance 1e-9` lets floats match within that share for numeric code |
|
|
190
|
-
| 3. Build | `rust-anything build <crate>` | Builds the Rust side: `.node`, wasm package, Python extension or shared library |
|
|
191
|
-
| 3. Diff | `rust-anything diff <crate>` | Replays the recorded cases against Rust, called the way the original's callers call it; lists mismatches |
|
|
192
|
-
| 3. Bench | `rust-anything bench <crate>` | Times the recorded cases on the original and on Rust, bridge included |
|
|
193
|
-
| 4. Shadow | `rust-anything shadow <crate>` | Drop-in that runs both, returns the original's result, reports mismatches; `RUST_ANYTHING_MODE=old\|shadow\|new` |
|
|
194
|
-
| 5. Gate | `rust-anything gate <crate>` | fmt, clippy `-D warnings`, tests, `unsafe` audit, nothing unported, a recorded failing case for every error path of the original, no `unwrap`/`expect`/`panic!` where the original returns an error (unless marked `// INFALLIBLE: <why>`), build, API, behavior |
|
|
195
|
-
| Agents | `rust-anything setup` | Registers the MCP server (`rust-anything mcp`, every step as a tool) and the workflow skill ([`skills/rust-anything/SKILL.md`](./skills/rust-anything/SKILL.md)) with your coding agents |
|
|
196
|
-
|
|
197
|
-
## Port a whole app
|
|
198
|
-
|
|
199
|
-
The goal is a pure Rust app that behaves like the original, with the original kept as reference.
|
|
200
|
-
Your agent writes the Rust; rust-anything orders the work, scaffolds it, and proves every step.
|
|
201
|
-
The [whole-app skill](./skills/rust-anything/whole-app.md) walks the agent through it, starting
|
|
202
|
-
with the decisions only you can make:
|
|
203
|
-
|
|
204
|
-
- **Grilling**: the agent asks in rounds, each question with its recommended answer, until every
|
|
205
|
-
decision the port depends on is settled, and writes each one as an ADR in `rust/DECISIONS.md`,
|
|
206
|
-
with `rust/GLOSSARY.md` mapping the original's terms to Rust names.
|
|
207
|
-
- **Research**: background agents read each dependency's primary sources and write
|
|
208
|
-
`rust/research/<topic>.md`, with every semantic trap they found.
|
|
209
|
-
- **Across sessions**: `rust/MAP.md` lists every unit with its state; a session claims one unit
|
|
210
|
-
before it starts, and each checkpoint leaves a `rust/HANDOFF.md` for the next session. Units in
|
|
211
|
-
one wave can be ported in parallel by subagents.
|
|
212
|
-
- **Cutover**: the agent does what it can and writes `rust/cutover.sh`, an interactive script for
|
|
213
|
-
the steps only you can do (deploys, DNS, secrets), with a way back at each step.
|
|
214
|
-
|
|
215
|
-
Grilling, research and these practices are adapted from
|
|
216
|
-
[Matt Pocock's skills](https://github.com/mattpocock/skills).
|
|
217
|
-
|
|
218
|
-
Plan first: `rust-anything analyze . --whole-app` adds the app's shape (CLI, server or library)
|
|
219
|
-
and entry points, every external dependency (imported or declared) with its Rust crate and fit,
|
|
220
|
-
the port order as pieces (units that import each other move together), and numbered decisions
|
|
221
|
-
with a recommended answer: keep units, blocked units, dependencies with no or a partial crate.
|
|
222
|
-
|
|
223
|
-
Then prove the whole program from the outside. `record` and `diff` prove one unit; `app record`
|
|
224
|
-
and `app replay` prove the app, for CLIs and servers in any of the six languages (the app is a
|
|
225
|
-
black box):
|
|
226
|
-
|
|
227
|
-
```sh
|
|
228
|
-
rust-anything app record . -- python3 cli.py # the command that runs the original
|
|
229
|
-
rust-anything app replay . # the original must pass 100%
|
|
230
|
-
rust-anything app replay . --build "target/release/mytool"
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
- `app record` runs the original on the app's own documented examples (`$ mytool ...` lines in
|
|
234
|
-
its Markdown and shell files, with the files they name), an `--inputs` JSONL file
|
|
235
|
-
(`{"name", "args", "stdin", "env", "files"}`), and semantic traps derived from those cases
|
|
236
|
-
(non-ASCII and emoji strings, negative division and modulo, overflow, large and tiny floats,
|
|
237
|
-
map order, missing files). Each case runs twice; what differs between the two runs becomes a
|
|
238
|
-
`[..]` wildcard. `--normalize timestamps|uuids|key-order` or `--normalize name=regex` adds
|
|
239
|
-
normalizers, saved with the cases.
|
|
240
|
-
- Cases are [trycmd](https://docs.rs/trycmd) files in `rust/app-cases/`: `<case>.toml` (argv, env,
|
|
241
|
-
exit code), `.stdin`, `.stdout`, `.stderr`, `.in/` (files in) and `.out/` (files written). Read
|
|
242
|
-
and edit them by hand; a Rust test can run them with `trycmd` once the port has a binary.
|
|
243
|
-
- `app replay` runs any build against the cases, prints `passed/total`, writes
|
|
244
|
-
`rust/app-cases/replay-report.md` with a diff per failing case, and exits non-zero on any
|
|
245
|
-
mismatch. A build that appends to the file named by `RUST_ANYTHING_FALLBACK_LOG` (one line per
|
|
246
|
-
fallback to the original), as the front door below does, also gets its fallback rate reported.
|
|
247
|
-
- `app replay --case <name>` reruns one case by the name the report gives it: the fast,
|
|
248
|
-
repeatable loop for fixing a mismatch before running everything again.
|
|
249
|
-
|
|
250
|
-
Then move the entry point to Rust and hand it commands one unit at a time:
|
|
251
|
-
|
|
252
|
-
```sh
|
|
253
|
-
rust-anything app front-door . # rust/app: every command runs the original
|
|
254
|
-
rust-anything app wire . textkit --command upper # after textkit-rs passes gate
|
|
255
|
-
# write the glue in rust/app/src/units/textkit.rs, then:
|
|
256
|
-
rust-anything app wire . textkit # 100% again, lower fallback rate
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
- `app front-door` scaffolds `rust/app`, a Rust binary named after the app: a clap parser for the
|
|
260
|
-
commands and flags in the recorded cases, where every command runs the original with the same
|
|
261
|
-
argv, stdin and environment and passes its output and exit code through. Each fallback is
|
|
262
|
-
counted, so replaying the fresh front door gives 100% passed at 100% fallback (it builds and
|
|
263
|
-
replays to show it). It never overwrites `rust/app`: the code is yours from then on.
|
|
264
|
-
- `app wire <repo> <unit> --command <name>` runs `gate` on the unit crate (`--skip-gate` if it just
|
|
265
|
-
passed), adds it to `rust/app` as a library, writes `src/units/<unit>.rs` once for you or your
|
|
266
|
-
agent to fill in (parse the arguments, call `<crate>::port`, print what the original prints),
|
|
267
|
-
routes the commands to it, then builds and replays. `RUST_ANYTHING_UNIT_<NAME>=original` sends a
|
|
268
|
-
wired unit back to the original until the lift.
|
|
269
|
-
|
|
270
|
-
Wire the app's own name as a command (`--command mytool`) for argv that names no command: no
|
|
271
|
-
arguments, unknown commands, usage errors.
|
|
272
|
-
|
|
273
|
-
When replay passes with fallback rate 0 and every unit passes gate, make it a pure Rust app:
|
|
274
|
-
|
|
275
|
-
```sh
|
|
276
|
-
rust-anything app lift .
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
- `app lift` refuses until both hold, and says what blocks it: the cases still falling back,
|
|
280
|
-
glue still a stub, units failing gate.
|
|
281
|
-
- On a copy first, it removes the fallback path and the kill switches, turns each unit crate into
|
|
282
|
-
a plain library of `rust/app` (no `cdylib`, bindings or generated wrappers), and adds
|
|
283
|
-
`rust/app/tests/app_cases.rs`, which runs `rust/app-cases` with trycmd on `cargo test`, so CI
|
|
284
|
-
needs nothing but cargo.
|
|
285
|
-
- Then it runs the lift checklist: fmt, clippy `-D warnings` and tests on every unit and on
|
|
286
|
-
`rust/app`, every target named in `rust/DECISIONS.md` built or checked where it is installed,
|
|
287
|
-
files read at run time and asset folders not embedded, and replay on the pure binary. Only when
|
|
288
|
-
all of it passes are the changes written back. The original is never touched.
|
|
206
|
+
## Learn more
|
|
289
207
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
```sh
|
|
297
|
-
rust-anything app record . --http -- node server.js
|
|
298
|
-
rust-anything app replay .
|
|
299
|
-
rust-anything app front-door . # axum: every route proxied
|
|
300
|
-
rust-anything app wire . api --route 'GET /users/{id}' --route '*'
|
|
301
|
-
rust-anything app lift .
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
- Requests come from `curl` lines in the app's docs (`curl -X POST -d ... http://localhost:8080/x`),
|
|
305
|
-
`--inputs` (`{"name", "method", "path", "headers", "body"}`) and traps: path segments and query
|
|
306
|
-
values swapped for the same traps as CLI arguments, bodies for text and JSON traps, and an
|
|
307
|
-
unknown route. Each run starts the server fresh and sends the requests in name order, so state
|
|
308
|
-
between requests is kept.
|
|
309
|
-
- Cases are `rust/app-cases/http/<case>.toml` (the request, the status and the headers that matter)
|
|
310
|
-
and `<case>.body` (the response body, with `[..]` where two runs differed). Date, server and
|
|
311
|
-
other per-response headers are left out; delete any header line you do not care about.
|
|
312
|
-
- The front door is an axum server that starts the original on a port of its own and proxies
|
|
313
|
-
every route no unit answers. `wire --route` takes axum routes: `METHOD /path/{param}`, `/path`
|
|
314
|
-
for any method, `*` for everything else; the glue gets the route, its parameters and the
|
|
315
|
-
request. `lift` removes the proxy; HTTP cases then run in CI with `app replay`.
|
|
316
|
-
|
|
317
|
-
### Libraries
|
|
318
|
-
|
|
319
|
-
A library has no process to replay: its public API is the front door, and each unit's recorded
|
|
320
|
-
cases are the proof.
|
|
321
|
-
|
|
322
|
-
```sh
|
|
323
|
-
rust-anything app front-door . # rust/app: a Rust crate with the public API
|
|
324
|
-
# each unit through the loop: bridge, record, port.rs, build, diff, gate; then:
|
|
325
|
-
rust-anything app wire . textkit-rs # re-exported from rust/app; the original imports its shadow
|
|
326
|
-
rust-anything app replay . # every wired unit's cases; fallback = exports still in the original
|
|
327
|
-
rust-anything app lift .
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
- `app front-door` finds the public API (every unit's exports) when the repository has no `main`
|
|
331
|
-
and no server (`--library` otherwise), and scaffolds `rust/app` as a library crate. Each wired
|
|
332
|
-
unit becomes a module of it: `pub use textkit_rs::port as textkit;`.
|
|
333
|
-
- `app wire` takes a crate made by `bridge`, runs `gate`, and writes the unit's shadow drop-in:
|
|
334
|
-
the original package imports it in place of the unit, so its callers keep the original API and
|
|
335
|
-
reach the Rust. `RUST_ANYTHING_UNIT_<NAME>=original` sends the unit back (C: build without the
|
|
336
|
-
shadow's flags).
|
|
337
|
-
- `app replay` runs every wired unit's recorded cases through its bindings. The fallback rate is
|
|
338
|
-
the share of public exports Rust does not answer yet: unwired units, and exports `bridge` keeps
|
|
339
|
-
in the original language.
|
|
340
|
-
- `app lift` needs fallback 0 and every unit through `gate`; it strips the bindings, wrappers and
|
|
341
|
-
shadows from the units and leaves `rust/app` as one pure Rust library. It does not touch any
|
|
342
|
-
`port.rs`, so the cases that matched through the bindings still describe it; the checklist
|
|
343
|
-
warns about files of the original that still import the shadows.
|
|
344
|
-
|
|
345
|
-
All five are MCP tools too: `app_record`, `app_replay`, `app_front_door`, `app_wire` and
|
|
346
|
-
`app_lift`.
|
|
347
|
-
|
|
348
|
-
## Case study: x18n's core
|
|
349
|
-
|
|
350
|
-
All 29 functions of x18n's core that can move without an API change were ported with rust-anything:
|
|
351
|
-
every gate passes and 7,925 recorded cases match exactly. `rust-anything bench` then showed the ports
|
|
352
|
-
are slower than the TS as called from JS, because the bridge costs more than the work. Full report:
|
|
353
|
-
[`demo/x18n-core`](./demo/x18n-core/README.md). The lesson is built in: measure with `bench` before
|
|
354
|
-
shipping a port.
|
|
355
|
-
|
|
356
|
-
## Hot paths: keep the data in Rust
|
|
357
|
-
|
|
358
|
-
A port called once per item pays the bridge once per item, and loses to a JIT. What wins is
|
|
359
|
-
moving the loop: `profile` finds it, and `--batch` generates a class that takes the items once
|
|
360
|
-
and runs the function over all of them per call, on all cores, with typed-array results.
|
|
361
|
-
|
|
362
|
-
```sh
|
|
363
|
-
rust-anything profile ../x18n -- node --experimental-strip-types $PWD/demo/x18n-search/search.ts .
|
|
364
|
-
# -> fuzzyScore: a quarter of the run, called per key by `matched`: batch it
|
|
365
|
-
rust-anything bridge ../x18n packages/core/src/fuzzy.ts --batch fuzzyScore:text
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
```js
|
|
369
|
-
const search = new FuzzyScoreBatch(keys) // once
|
|
370
|
-
const order = search.rank(query, 0) // per keystroke: indexes, best first
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
A `FuzzyScoreIndex` struct in `port.rs` replaces the default loop with one that prepares the
|
|
374
|
-
items once, and can rank by itself (`rank`): it keeps the keys lowercased with a character mask
|
|
375
|
-
each, a table of each key's first position of every common character (a one-letter query is one
|
|
376
|
-
column), and the last query's matches (typing `se` after `s` rescores only what `s` matched). On
|
|
377
|
-
x18n's sidebar search over 50,000 keys, typed letter by letter, with identical results:
|
|
378
|
-
|
|
379
|
-
| | Per query | vs TS |
|
|
380
|
-
| --- | ---: | ---: |
|
|
381
|
-
| TS: `map(fuzzyScore)`, filter, sort | 10 ms | 1x |
|
|
382
|
-
| TS with the same narrowing as the index | 4.1-5.4 ms | 2x |
|
|
383
|
-
| The same port, called per key | - | 0.2-0.4x |
|
|
384
|
-
| `FuzzyScoreBatch`, default index (4 cores) | 5.1 ms | 1.7x |
|
|
385
|
-
| `FuzzyScoreBatch` with `FuzzyScoreIndex` (napi, 4 cores) | 0.45-0.56 ms | **18-22x** |
|
|
386
|
-
| The same with wasm (one thread) | 0.95 ms | **11.5x** |
|
|
387
|
-
|
|
388
|
-
Against TS doing the same narrowing, Rust is still 7-12x faster (wasm 5x). Turn the returned
|
|
389
|
-
indexes into keys with a plain loop: `Array.from(order, i => keys[i])` cost 20x more, 0.4 ms.
|
|
390
|
-
|
|
391
|
-
Every language gets batches, and they beat the original even where per-call ports lose. The
|
|
392
|
-
same work on 4 cores, identical results and errors (benchmarks in each demo folder):
|
|
393
|
-
|
|
394
|
-
| Language | Workload | Original | Per-call port vs original | Batch vs original |
|
|
395
|
-
| --- | --- | ---: | ---: | ---: |
|
|
396
|
-
| TS | x18n search, 50,000 keys | 10 ms | 0.2-0.4x | **20x** |
|
|
397
|
-
| Python | `slugify`, 20,000 strings | 98 ms | - | **17x** |
|
|
398
|
-
| Ruby | `slugify`, 20,000 strings | 110 ms | - | **12.7x** |
|
|
399
|
-
| Ruby | `shellescape` (stdlib), 50,000 mixed values | 88 ms | - | **11.8x** |
|
|
400
|
-
| Go | `Slugify`, 50,000 strings | 49 ms | 0.93x | **4x** |
|
|
401
|
-
| Java | `slugify`, 50,000 strings | 43 ms | 0.68x | **3x** |
|
|
402
|
-
|
|
403
|
-
Compiled originals gain less: the per-item work is already fast, so the batch wins by the number of
|
|
404
|
-
cores. Batch crates allocate with mimalloc: with the system allocator the Go batch was slower than
|
|
405
|
-
one thread. Demo: [`demo/x18n-search`](./demo/x18n-search/README.md).
|
|
406
|
-
|
|
407
|
-
## Real code in six languages
|
|
408
|
-
|
|
409
|
-
Go's `path`, Ruby's `shellwords`, Python's `colorsys`, JDK and glibc behavior behind small
|
|
410
|
-
facades: every port passes its gate, 13,010 recorded cases in all. The runs found and fixed
|
|
411
|
-
bugs in rust-anything (floats off by one ULP through `serde_json`, C crashes during recording,
|
|
412
|
-
untyped code getting garbage inputs). Called per function, the Ruby port runs 4.4x faster than
|
|
413
|
-
Ruby and the Python port 1.35x faster than CPython, while Go and Java leaf functions stay faster
|
|
414
|
-
in their own language; as batches, all of them win (see the table above).
|
|
415
|
-
Report: [`docs/real-world-languages.md`](./docs/real-world-languages.md).
|
|
416
|
-
|
|
417
|
-
## Example: a real module from x18n
|
|
418
|
-
|
|
419
|
-
`packages/core/src/fuzzy.ts` from [x18n](https://github.com/x18n-dev/x18n), ported both ways in
|
|
420
|
-
[`demo/`](./demo):
|
|
421
|
-
|
|
422
|
-
```sh
|
|
423
|
-
rust-anything analyze ../x18n # fuzzy.ts: ready, wasm-bindgen (core runs in browsers)
|
|
424
|
-
rust-anything bridge ../x18n packages/core/src/fuzzy.ts --out demo/fuzzy-rs
|
|
425
|
-
rust-anything record demo/fuzzy-rs --count 2000
|
|
426
|
-
# write src/port.rs
|
|
427
|
-
rust-anything gate demo/fuzzy-rs
|
|
428
|
-
```
|
|
429
|
-
|
|
430
|
-
A first port that indexed by Rust `char` passed simple tests but failed `diff`:
|
|
431
|
-
|
|
432
|
-
```
|
|
433
|
-
198/200 cases match
|
|
434
|
-
- fuzzyScore("b😀", "a😀b😀c"): expected {"ok":1997}, got {"ok":1998}
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
JS `indexOf` counts UTF-16 code units, so an emoji is two positions. The port in
|
|
438
|
-
`demo/*/src/port.rs` uses the generated `utf16` helpers and passes 2000/2000 cases and the gate,
|
|
439
|
-
as napi-rs (`demo/fuzzy-napi`) and as wasm-bindgen (`demo/fuzzy-rs`).
|
|
440
|
-
|
|
441
|
-
The plan rust-anything writes for all of x18n: [`docs/examples/x18n.md`](./docs/examples/x18n.md).
|
|
442
|
-
|
|
443
|
-
## Install
|
|
444
|
-
|
|
445
|
-
```sh
|
|
446
|
-
cargo install --path .
|
|
447
|
-
```
|
|
448
|
-
|
|
449
|
-
`record`, `diff` and `bench` run the original in its own runtime: Node 22.6+ for TS (it runs `.ts`
|
|
450
|
-
sources directly), Python 3.9+ for Python and C (ctypes), Go 1.21+, Ruby 3+, JDK 17+
|
|
451
|
-
(`javac` and `java`). `profile` on Node needs Node 24+, which allows `--cpu-prof` in `NODE_OPTIONS`. C also needs a C compiler. wasm bridges also need `rustup target add wasm32-unknown-unknown` and
|
|
452
|
-
`cargo install wasm-bindgen-cli --version <the crate's wasm-bindgen version> --locked`; `build` names
|
|
453
|
-
the exact version.
|
|
454
|
-
|
|
455
|
-
### Windows
|
|
456
|
-
|
|
457
|
-
Native Windows CI uses the `x86_64-pc-windows-msvc` Rust target. Install the stable MSVC
|
|
458
|
-
toolchain and Visual Studio Build Tools with the **Desktop development with C++** workload; the
|
|
459
|
-
C compiler and linker are required for C bridges and native Rust extensions. Install the runtime
|
|
460
|
-
for the source language you are migrating. Python may be available as either `python3` or
|
|
461
|
-
`python`; rust-anything detects both. The GNU Windows target is not exercised by CI.
|
|
462
|
-
|
|
463
|
-
Run the native bridge integration suite from a Developer PowerShell prompt:
|
|
464
|
-
|
|
465
|
-
```powershell
|
|
466
|
-
rustup default stable-x86_64-pc-windows-msvc
|
|
467
|
-
cargo test --locked --test native -- --nocapture
|
|
468
|
-
```
|
|
469
|
-
|
|
470
|
-
The suite builds and loads real DLL-backed Node and Python extensions and the supported native
|
|
471
|
-
bridges for each runtime present on `PATH`. Missing optional runtimes are reported as skipped;
|
|
472
|
-
Cargo, the active Rust standard library, and the MSVC linker are required. If Cargo reports that
|
|
473
|
-
it cannot find `std`, reinstall the active target with
|
|
474
|
-
`rustup target remove x86_64-pc-windows-msvc` followed by
|
|
475
|
-
`rustup target add x86_64-pc-windows-msvc`. If linking fails, run from a Visual Studio Developer
|
|
476
|
-
PowerShell and verify that `where.exe link` finds the MSVC linker. Tests use temporary folders,
|
|
477
|
-
including a path with spaces and Unicode characters, and remove generated artifacts after a
|
|
478
|
-
successful run.
|
|
479
|
-
|
|
480
|
-
For agents, `rust-anything setup` registers everything (see Quick start). To add the MCP server to
|
|
481
|
-
one project by hand instead (`.mcp.json`):
|
|
482
|
-
|
|
483
|
-
```json
|
|
484
|
-
{ "mcpServers": { "rust-anything": { "command": "rust-anything", "args": ["mcp"] } } }
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
## What `bridge` decides
|
|
488
|
-
|
|
489
|
-
- Exports that cannot cross a bridge stay in the source language, with the reason, and the shadow
|
|
490
|
-
module re-exports the original. For TS:
|
|
491
|
-
functions that take or return functions, generators and iterators, RegExp, `instanceof` checks,
|
|
492
|
-
generics, and values whose types (followed through imports, re-exports and `extends`) hold
|
|
493
|
-
functions. `--keep "name: reason"` keeps more, e.g. code that depends on `Intl` data.
|
|
494
|
-
- TS types map to Rust types, with type aliases resolved through imports and parameter types
|
|
495
|
-
inferred from default values; structured values cross as a generated binary wire (JSON only
|
|
496
|
-
as a fallback for shapes the wire does not model).
|
|
497
|
-
- JSON cannot express `undefined`, NaN, Infinity, -0 or lone surrogates: structured values carry
|
|
498
|
-
markers (`{"$undefined": true}`, `{"$num": "NaN"}`, `{"$utf16": [...]}`) that the generated
|
|
499
|
-
`index.cjs` translates, with helpers in the crate's `js.rs`.
|
|
500
|
-
|
|
501
|
-
`record` runs TS sources as they are: a Node resolve hook follows bundler-style imports
|
|
502
|
-
(`./errors` to `./errors.ts`), `--resolve-from` supplies npm packages when the repo has none
|
|
503
|
-
installed, and TS that needs transforming (enums, parameter properties) is retried with
|
|
504
|
-
`--experimental-transform-types`.
|
|
505
|
-
|
|
506
|
-
## What `analyze` looks at
|
|
507
|
-
|
|
508
|
-
- Packages (`package.json`) and source files; skips `node_modules`, build output, fixtures,
|
|
509
|
-
playgrounds, tool configs. Vue/Svelte/Astro `<script>` blocks are parsed for imports.
|
|
510
|
-
- **Units**: a folder of source files, or a file at a package's source root.
|
|
511
|
-
- **Waves**: a unit's imports come in earlier waves; import cycles are ported together.
|
|
512
|
-
- **Bridge**: napi-rs when the unit or anything it imports needs Node; wasm-bindgen for portable
|
|
513
|
-
code; keep in JS for UI and editor code.
|
|
514
|
-
- **Readiness** (how safe) and **priority** (safe and worth it: loops and string work, tests, size).
|
|
515
|
-
|
|
516
|
-
| Risk | Severity | Example |
|
|
517
|
-
| --- | --- | --- |
|
|
518
|
-
| String offsets | high | `slice`, `indexOf`, `matchAll`, the `d` flag: UTF-16 vs UTF-8 |
|
|
519
|
-
| Regex syntax | high | lookaround, backreferences, `y`: not in the `regex` crate |
|
|
520
|
-
| Dynamic regex | high | `new RegExp(userPattern)`: JS syntax at runtime |
|
|
521
|
-
| Dynamic code | high | `eval`, `new Function`, computed `import()` |
|
|
522
|
-
| Dynamic typing | medium | `any`, `'key' in value` |
|
|
523
|
-
| Ordered collections | medium | `Map`, `Set`, `Object.keys`: insertion order |
|
|
524
|
-
| Async, generators | medium | promise and generator boundaries |
|
|
525
|
-
| Class inheritance, reflection | medium | `extends`, `Proxy`, `Reflect`, `Symbol` |
|
|
526
|
-
| Callback-shaped APIs | medium | function-typed params and methods: chatty bridges |
|
|
527
|
-
| Exceptions, numbers, JSON | low | `throw`, bitwise ops, `JSON.stringify` order |
|
|
528
|
-
|
|
529
|
-
## Development
|
|
530
|
-
|
|
531
|
-
```sh
|
|
532
|
-
cargo test # unit tests, fixture repo, record/diff/shadow loop (needs node), app record/replay per language
|
|
533
|
-
cargo clippy --all-targets -- -D warnings
|
|
534
|
-
cargo fmt
|
|
535
|
-
```
|
|
536
|
-
|
|
537
|
-
Design choices and their reasons: [DECISIONS.md](./DECISIONS.md).
|
|
538
|
-
|
|
539
|
-
## Update or remove
|
|
540
|
-
|
|
541
|
-
```sh
|
|
542
|
-
cargo install rust-anything # update (Cargo)
|
|
543
|
-
npm install -g rust-anything@latest # update (npm)
|
|
544
|
-
rust-anything setup # refresh agent settings
|
|
545
|
-
rust-anything setup --remove && cargo uninstall rust-anything # remove (Cargo)
|
|
546
|
-
rust-anything setup --remove && npm uninstall -g rust-anything # remove (npm)
|
|
547
|
-
```
|
|
548
|
-
|
|
549
|
-
`setup --remove` takes out only rust-anything's entries; the copies it saved
|
|
550
|
-
(`<file>.rust-anything.bak`) stay until you delete them.
|
|
551
|
-
|
|
552
|
-
## What it can't catch
|
|
553
|
-
|
|
554
|
-
Passing means the Rust matches every case that was recorded, nothing more. What bites rewrites
|
|
555
|
-
usually lives outside the recording, so know where the edges are:
|
|
556
|
-
|
|
557
|
-
- **Inputs nobody recorded.** The generated cases, the traps and your own `--inputs` are the
|
|
558
|
-
ceiling. Add real inputs (production samples, bug reports, the original's test fixtures); the
|
|
559
|
-
user input that breaks prod is rarely one a generator thinks of.
|
|
560
|
-
- **Regexes.** The `regex` crate has no lookaround or backreferences, and even a pattern that
|
|
561
|
-
compiles can treat `\w`, `\b`, `\d` and case-insensitive matching on non-ASCII text differently
|
|
562
|
-
from JS, Python or Java. Swapping in `fancy-regex` or rewriting the pattern can pass every
|
|
563
|
-
recorded case and still differ on a Turkish dotless `ı` or a zero-width joiner. `record` adds
|
|
564
|
-
regex traps (those, the Kelvin sign, long s, Arabic-Indic digits, line separators, final sigma)
|
|
565
|
-
to every function in a file that uses regexes, but fuzz your real patterns against real text too.
|
|
566
|
-
- **What changes between runs.** `record` runs the original twice and sorts out what differed:
|
|
567
|
-
changed values (times, ids) become wildcards; the same lines in another order (hash maps,
|
|
568
|
-
concurrency) are compared in any order, so a port still has to produce exactly those lines; a
|
|
569
|
-
different number of lines becomes `...`, which matches anything. `record` lists each kind:
|
|
570
|
-
look at every one, since a hash-order or concurrency difference is exactly what can change for
|
|
571
|
-
real in a port.
|
|
572
|
-
- **Floats.** Number-to-text formatting differs between languages (`1e21`, `-0`, digit counts).
|
|
573
|
-
The traps include those values, and they must match exactly; `--float-tolerance` forgives
|
|
574
|
-
rounding only, never formatting.
|
|
575
|
-
- **Anything not in the output.** Timing, memory, concurrency under load, and side effects other
|
|
576
|
-
than stdout, stderr, exit codes, written files and HTTP responses (network calls, databases,
|
|
577
|
-
signals) are not compared.
|
|
578
|
-
- **Other platforms.** A recording proves behavior on the machine that ran it. C whose results
|
|
579
|
-
depend on type sizes, endianness or the compiler can behave differently on the target; `analyze`
|
|
580
|
-
keeps hardware-facing C in C for that reason.
|
|
581
|
-
|
|
582
|
-
## FAQ
|
|
583
|
-
|
|
584
|
-
**Does it rewrite my code automatically?** No. It finds what to move, generates the bridge,
|
|
585
|
-
records what the original does and checks the Rust against it. You or your agent write the Rust
|
|
586
|
-
in `port.rs`; `diff` and `gate` decide when it is right.
|
|
587
|
-
|
|
588
|
-
**Will my app's API change?** No. Callers import the same functions (or the shadow module, which
|
|
589
|
-
runs both and returns the original's result while you build confidence).
|
|
590
|
-
|
|
591
|
-
**Is Rust always faster?** No, and rust-anything says so. A small function called once per item
|
|
592
|
-
is often slower in Rust, because each call crosses a bridge; V8, the JVM and Go run such functions
|
|
593
|
-
in nanoseconds. `profile` finds the loop around it, `--batch` moves the whole loop, and `bench`
|
|
594
|
-
gives a verdict before you ship. Code already compiled by numba, Cython or JAX runs as machine
|
|
595
|
-
code too: `profile` and `analyze` flag it, since porting it buys little speed.
|
|
596
|
-
|
|
597
|
-
**My code is numeric; will the floats match exactly?** Often not: operation order, fused
|
|
598
|
-
multiply-add and the math library differ between compilers. Record with `--float-tolerance 1e-9`
|
|
599
|
-
(`record` or `app record`), and floats match within that share of the larger value (absolute below
|
|
600
|
-
1). Integers, text and structure still have to match exactly.
|
|
601
|
-
|
|
602
|
-
**Can it port an app I only have as an APK, a JAR or an .exe?** No. It ports source code: it
|
|
603
|
-
parses the functions, records what each one does, and checks the Rust against the running
|
|
604
|
-
original. A compiled app has none of that to work with, and `analyze` says so. Writing a new Rust
|
|
605
|
-
app from a binary's visible behavior is a different project.
|
|
606
|
-
|
|
607
|
-
**Should I port battle-tested C?** Often not, and `analyze` tells you where. C that touches
|
|
608
|
-
hardware registers, relies on its compiler's type sizes or memory layout, or uses inline assembly
|
|
609
|
-
(`volatile`, bitfields, packed structs, `__asm__`, integers cast to addresses) is marked "keep in
|
|
610
|
-
C": a recording on your machine proves nothing about the target, and stable driver or firmware
|
|
611
|
-
code gains little from a rewrite. The portable logic around it (parsing, protocols, data handling)
|
|
612
|
-
is what moves well.
|
|
613
|
-
|
|
614
|
-
**Can it port my Electron app?** The logic, yes; the windows stay web pages. `analyze
|
|
615
|
-
--whole-app` spots Electron and plans the main process piece by piece while the renderer stays as
|
|
616
|
-
it is. Moving the UI to Tauri (the same web UI on a Rust backend) is a separate step once the logic
|
|
617
|
-
is Rust.
|
|
618
|
-
|
|
619
|
-
**What about C#, Kotlin or Swift?** C# is in preview (see [Languages](#languages)); Kotlin and
|
|
620
|
-
Swift are not supported yet. Each language needs a parser, a recorder, a bridge and a replay
|
|
621
|
-
driver, all tested end to end. Open an issue (or upvote one) for the language you need.
|
|
622
|
-
|
|
623
|
-
**Won't the Rust be much bigger than the original?** It shouldn't be. `gate` compares the port's
|
|
624
|
-
lines with the original's and fails above 3x (plus 50 lines for imports and signatures): that usually means hand-writing what a crate already
|
|
625
|
-
does, or handling cases one by one. `analyze` lists the crates to use.
|
|
626
|
-
|
|
627
|
-
**Doesn't porting piece by piece lock the Rust into the old app's design?** Only while both run
|
|
628
|
-
side by side. The recordings check behavior at the app's edges (a CLI's output, a server's
|
|
629
|
-
responses, a module's exported functions), not its internals. Mirror the old structure while
|
|
630
|
-
units still cross the bridge; once `app lift` has removed the original, restructure the Rust
|
|
631
|
-
freely, and `app replay` still proves the behavior. Nothing calls back into the original either:
|
|
632
|
-
the front door runs it as a separate process (or forwards HTTP to it), bridged units are called
|
|
633
|
-
by the original and never the other way round, and callbacks stay in the source language.
|
|
634
|
-
|
|
635
|
-
**Does my code leave my machine?** No: rust-anything runs locally and sends none of your code
|
|
636
|
-
anywhere. Cargo downloads crates as usual, and your agent's model provider sees what your agent
|
|
637
|
-
sends it, under its own policy.
|
|
638
|
-
|
|
639
|
-
**What does it need installed?** Rust, plus the runtime of the language you port (see
|
|
640
|
-
[Install](#install)).
|
|
641
|
-
|
|
642
|
-
**Something broke.** Open an issue with the command, its output and your platform.
|
|
208
|
+
- [How it works](docs/how-it-works.md): the loop, what `bridge` and `analyze` decide, hot paths, what it can't catch, what a real port takes, and keeping up with the original (`map`)
|
|
209
|
+
- [Port a whole app](docs/whole-apps.md): servers, CLIs and libraries, from the front door to `app lift`
|
|
210
|
+
- [Examples and case studies](docs/examples.md): x18n, and real code in six languages
|
|
211
|
+
- [Real-world ports](docs/real-world.md): json-server, Fuse.js, vercel/ms, with benchmarks
|
|
212
|
+
- [Install, update and develop](docs/install.md): every install method, Windows, and building from source
|
|
213
|
+
- [FAQ](docs/faq.md) · [Status](docs/STATUS.md) · [MCP tools](docs/tools.md)
|
|
643
214
|
|
|
644
215
|
## Sponsors
|
|
645
216
|
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
<a href="https://github.com/sponsors/erkamyaman"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?logo=githubsponsors&logoColor=white" alt="Sponsor rust-anything on GitHub" /></a>
|
|
217
|
+
<p align="center">
|
|
218
|
+
<a href="https://github.com/erkamyaman/rust-anything">rust-anything</a> is free and open source. If it helps your work, please consider sponsoring it.<br>
|
|
219
|
+
Your support keeps development going.
|
|
650
220
|
</p>
|
|
651
221
|
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
<
|
|
656
|
-
|
|
222
|
+
<p align="center">
|
|
223
|
+
<a href="https://coderabbit.ai">
|
|
224
|
+
<picture>
|
|
225
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/sponsors/company-dark.svg">
|
|
226
|
+
<img src="docs/assets/sponsors/company-light.svg" width="800" alt="Company sponsor: CodeRabbit">
|
|
227
|
+
</picture>
|
|
228
|
+
</a>
|
|
229
|
+
</p>
|
|
657
230
|
|
|
658
|
-
|
|
231
|
+
<p align="center">
|
|
232
|
+
<a href="https://github.com/sponsors/erkamyaman">
|
|
233
|
+
<picture>
|
|
234
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/sponsors/sponsors-dark.svg">
|
|
235
|
+
<img src="docs/assets/sponsors/sponsors-light.svg" width="800" alt="Sponsors: Ali Yilmaz, Ashley Hunter, Fatih Uzuntaş">
|
|
236
|
+
</picture>
|
|
237
|
+
</a>
|
|
238
|
+
</p>
|
|
659
239
|
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
<tbody>
|
|
664
|
-
<tr>
|
|
665
|
-
<td align="center" valign="top" width="14.28%"><a href="https://github.com/aliyilmazco"><img src="https://github.com/aliyilmazco.png?size=100" width="80px;" alt="Ali Yilmaz"/><br /><sub><b>Ali Yilmaz</b></sub></a></td>
|
|
666
|
-
</tr>
|
|
667
|
-
</tbody>
|
|
668
|
-
</table>
|
|
669
|
-
<!-- prettier-ignore-end -->
|
|
670
|
-
<!-- /sponsors -->
|
|
240
|
+
<p align="center">
|
|
241
|
+
<a href="https://github.com/sponsors/erkamyaman"><img src="https://img.shields.io/badge/Become_a_sponsor-%E2%9D%A4-db61a2?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Become a sponsor"></a>
|
|
242
|
+
</p>
|
|
671
243
|
|
|
672
244
|
## Contributing
|
|
673
245
|
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rust-anything",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
4
|
"description": "Rewrite your app in Rust, one piece at a time, checked against the original's recorded behavior at every step. TypeScript, Python, C, Go, Ruby, Java.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"rust",
|