rust-anything 1.1.0 → 1.3.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/LICENSE +1 -1
- package/README.md +144 -24
- package/bin/rust-anything.js +1 -1
- package/binaries/darwin-arm64/rust-anything +0 -0
- package/binaries/darwin-x64/rust-anything +0 -0
- package/binaries/linux-arm64/rust-anything +0 -0
- package/binaries/linux-x64/rust-anything +0 -0
- package/binaries/win32-x64/rust-anything.exe +0 -0
- package/package.json +2 -2
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,11 +1,31 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="docs/assets/
|
|
2
|
+
<img src="docs/assets/logo.svg" width="160" height="160" alt="The rust-anything crab, its mouth a code tag">
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
<h1 align="center">rust-anything</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center"><em>Rewrite your whole app in Rust. Keep it working the whole way.</em></p>
|
|
8
|
+
|
|
9
|
+
<p align="center"><em>CLIs, servers and libraries, piece by piece, checked against the original at every step.</em></p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
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>
|
|
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>
|
|
14
|
+
<img src="https://img.shields.io/badge/languages-6-E2862A" alt="6 languages">
|
|
15
|
+
<a href="#works-with"><img src="https://img.shields.io/badge/works%20with-4%20agents-E2862A" alt="Works with 4 agents"></a>
|
|
16
|
+
<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>
|
|
17
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-E2862A" alt="MIT license"></a>
|
|
18
|
+
<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>
|
|
19
|
+
</p>
|
|
20
|
+
|
|
21
|
+
<p align="center">up to 20x faster · 38,251 recorded cases replayed · 0 mismatches · one command</p>
|
|
22
|
+
|
|
23
|
+
**Rewrite your whole app in Rust, one piece at a time.** rust-anything records what your
|
|
24
|
+
TypeScript/JavaScript, Python, C, Go, Ruby or Java app does today, then checks every piece of the
|
|
25
|
+
Rust rewrite against that recording before it moves on, until the app is pure Rust. CLIs, HTTP
|
|
26
|
+
servers and libraries; your coding agent (or you) writes the Rust. It can only catch what the
|
|
27
|
+
recording covers: see [What it can't catch](#what-it-cant-catch). Only need the slow part fast?
|
|
28
|
+
Port just that, one hot path at a time:
|
|
9
29
|
|
|
10
30
|
| Real workload, same results as the original | Original | With rust-anything |
|
|
11
31
|
| --- | ---: | ---: |
|
|
@@ -32,19 +52,20 @@ rust-anything finds the loop worth moving, and moves it.
|
|
|
32
52
|
Paste this into Claude Code, Codex, Cursor or Gemini CLI and let your agent install it:
|
|
33
53
|
|
|
34
54
|
```text
|
|
35
|
-
Install rust-anything: run `cargo install
|
|
36
|
-
|
|
55
|
+
Install rust-anything: run `cargo install rust-anything`, then `rust-anything setup`.
|
|
56
|
+
Tell me when to restart you.
|
|
37
57
|
```
|
|
38
58
|
|
|
39
59
|
Or yourself:
|
|
40
60
|
|
|
41
61
|
```sh
|
|
42
|
-
|
|
43
|
-
# or: cargo install --git https://github.com/erkamyaman/rust-anything
|
|
62
|
+
cargo install rust-anything # from crates.io
|
|
44
63
|
rust-anything setup # registers it with Claude Code, Codex, Cursor and Gemini CLI
|
|
45
64
|
```
|
|
46
65
|
|
|
47
|
-
Prebuilt binaries are
|
|
66
|
+
No Rust toolchain yet? Prebuilt binaries for macOS, Linux and Windows are attached to each
|
|
67
|
+
[GitHub release](https://github.com/erkamyaman/rust-anything/releases), and for JavaScript
|
|
68
|
+
projects `npm install -g rust-anything` installs the same binary.
|
|
48
69
|
|
|
49
70
|
In Claude Code you can also install it as a plugin (the MCP server and the skill; the CLI above
|
|
50
71
|
must be on your `PATH`):
|
|
@@ -107,14 +128,28 @@ done.
|
|
|
107
128
|
| 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 |
|
|
108
129
|
| Ruby | file or folder of module functions | a magnus extension under the original modules | a generated Ruby driver |
|
|
109
130
|
| Java | package of `public static` methods | typed JNI and a generated binary wire, in wrapper classes with the original methods | a generated reflection driver |
|
|
131
|
+
| PHP (preview) | 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`) |
|
|
132
|
+
| C# (preview) | 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`) |
|
|
110
133
|
|
|
111
134
|
Every language except C also gets batch classes (`--batch`): the items cross once and stay in
|
|
112
135
|
Rust, and each call runs over all of them on all cores.
|
|
113
136
|
|
|
114
|
-
The language is detected from the repository (`go.mod`, `pom.xml`, `
|
|
115
|
-
`package.json`, else the most common source files);
|
|
116
|
-
source: TS types, Python hints, C
|
|
117
|
-
used as numbers are inferred
|
|
137
|
+
The language is detected from the repository (`go.mod`, `pom.xml`, a `.csproj` or `.sln`,
|
|
138
|
+
`pyproject.toml`, `Gemfile`, `composer.json`, `package.json`, else the most common source files);
|
|
139
|
+
`--lang` overrides it. Types come from the source: TS types, Python hints, C, Go, Java and C#
|
|
140
|
+
signatures, Ruby YARD tags, PHP types and phpdoc; untyped parameters used as numbers are inferred
|
|
141
|
+
as numbers.
|
|
142
|
+
|
|
143
|
+
PHP is in preview: `analyze` plans a PHP app (Composer packages and PSR-4 autoloading, risks
|
|
144
|
+
such as loose comparison and integer overflow into floats, Composer packages mapped to crates),
|
|
145
|
+
and a PHP CLI or server can be recorded, replayed and put behind a Rust front door. Porting its
|
|
146
|
+
units into Rust through PHP's FFI is the next step ([issue #2](https://github.com/erkamyaman/rust-anything/issues/2)).
|
|
147
|
+
|
|
148
|
+
C# is in preview the same way: `analyze` reads `.csproj` projects and their NuGet packages
|
|
149
|
+
(mapped to crates), resolves `using` directives to folders, and flags what C# does differently
|
|
150
|
+
(`decimal`, `dynamic`, LINQ's deferred queries, `Task`, `lock`, reflection). A C# CLI or ASP.NET
|
|
151
|
+
server can be recorded, replayed and put behind a Rust front door; porting units through P/Invoke
|
|
152
|
+
comes next.
|
|
118
153
|
|
|
119
154
|
## How it works
|
|
120
155
|
|
|
@@ -143,10 +178,10 @@ analyze --whole-app ──> app record ──> app front-door ──> per unit:
|
|
|
143
178
|
|
|
144
179
|
| Step | Command | What it does |
|
|
145
180
|
| --- | --- | --- |
|
|
146
|
-
| 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 |
|
|
181
|
+
| 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 |
|
|
147
182
|
| 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 |
|
|
148
183
|
| 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 |
|
|
149
|
-
| 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` |
|
|
184
|
+
| 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 |
|
|
150
185
|
| 3. Build | `rust-anything build <crate>` | Builds the Rust side: `.node`, wasm package, Python extension or shared library |
|
|
151
186
|
| 3. Diff | `rust-anything diff <crate>` | Replays the recorded cases against Rust, called the way the original's callers call it; lists mismatches |
|
|
152
187
|
| 3. Bench | `rust-anything bench <crate>` | Times the recorded cases on the original and on Rust, bridge included |
|
|
@@ -159,7 +194,21 @@ analyze --whole-app ──> app record ──> app front-door ──> per unit:
|
|
|
159
194
|
The goal is a pure Rust app that behaves like the original, with the original kept as reference.
|
|
160
195
|
Your agent writes the Rust; rust-anything orders the work, scaffolds it, and proves every step.
|
|
161
196
|
The [whole-app skill](./skills/rust-anything/whole-app.md) walks the agent through it, starting
|
|
162
|
-
with the decisions only you can make
|
|
197
|
+
with the decisions only you can make:
|
|
198
|
+
|
|
199
|
+
- **Grilling**: the agent asks in rounds, each question with its recommended answer, until every
|
|
200
|
+
decision the port depends on is settled, and writes each one as an ADR in `rust/DECISIONS.md`,
|
|
201
|
+
with `rust/GLOSSARY.md` mapping the original's terms to Rust names.
|
|
202
|
+
- **Research**: background agents read each dependency's primary sources and write
|
|
203
|
+
`rust/research/<topic>.md`, with every semantic trap they found.
|
|
204
|
+
- **Across sessions**: `rust/MAP.md` lists every unit with its state; a session claims one unit
|
|
205
|
+
before it starts, and each checkpoint leaves a `rust/HANDOFF.md` for the next session. Units in
|
|
206
|
+
one wave can be ported in parallel by subagents.
|
|
207
|
+
- **Cutover**: the agent does what it can and writes `rust/cutover.sh`, an interactive script for
|
|
208
|
+
the steps only you can do (deploys, DNS, secrets), with a way back at each step.
|
|
209
|
+
|
|
210
|
+
Grilling, research and these practices are adapted from
|
|
211
|
+
[Matt Pocock's skills](https://github.com/mattpocock/skills).
|
|
163
212
|
|
|
164
213
|
Plan first: `rust-anything analyze . --whole-app` adds the app's shape (CLI, server or library)
|
|
165
214
|
and entry points, every external dependency (imported or declared) with its Rust crate and fit,
|
|
@@ -190,6 +239,8 @@ rust-anything app replay . --build "target/release/mytool"
|
|
|
190
239
|
`rust/app-cases/replay-report.md` with a diff per failing case, and exits non-zero on any
|
|
191
240
|
mismatch. A build that appends to the file named by `RUST_ANYTHING_FALLBACK_LOG` (one line per
|
|
192
241
|
fallback to the original), as the front door below does, also gets its fallback rate reported.
|
|
242
|
+
- `app replay --case <name>` reruns one case by the name the report gives it: the fast,
|
|
243
|
+
repeatable loop for fixing a mismatch before running everything again.
|
|
193
244
|
|
|
194
245
|
Then move the entry point to Rust and hand it commands one unit at a time:
|
|
195
246
|
|
|
@@ -459,16 +510,46 @@ Design choices and their reasons: [DECISIONS.md](./DECISIONS.md).
|
|
|
459
510
|
## Update or remove
|
|
460
511
|
|
|
461
512
|
```sh
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
rust-anything setup
|
|
465
|
-
rust-anything setup --remove &&
|
|
466
|
-
rust-anything setup --remove &&
|
|
513
|
+
cargo install rust-anything # update (Cargo)
|
|
514
|
+
npm install -g rust-anything@latest # update (npm)
|
|
515
|
+
rust-anything setup # refresh agent settings
|
|
516
|
+
rust-anything setup --remove && cargo uninstall rust-anything # remove (Cargo)
|
|
517
|
+
rust-anything setup --remove && npm uninstall -g rust-anything # remove (npm)
|
|
467
518
|
```
|
|
468
519
|
|
|
469
520
|
`setup --remove` takes out only rust-anything's entries; the copies it saved
|
|
470
521
|
(`<file>.rust-anything.bak`) stay until you delete them.
|
|
471
522
|
|
|
523
|
+
## What it can't catch
|
|
524
|
+
|
|
525
|
+
Passing means the Rust matches every case that was recorded, nothing more. What bites rewrites
|
|
526
|
+
usually lives outside the recording, so know where the edges are:
|
|
527
|
+
|
|
528
|
+
- **Inputs nobody recorded.** The generated cases, the traps and your own `--inputs` are the
|
|
529
|
+
ceiling. Add real inputs (production samples, bug reports, the original's test fixtures); the
|
|
530
|
+
user input that breaks prod is rarely one a generator thinks of.
|
|
531
|
+
- **Regexes.** The `regex` crate has no lookaround or backreferences, and even a pattern that
|
|
532
|
+
compiles can treat `\w`, `\b`, `\d` and case-insensitive matching on non-ASCII text differently
|
|
533
|
+
from JS, Python or Java. Swapping in `fancy-regex` or rewriting the pattern can pass every
|
|
534
|
+
recorded case and still differ on a Turkish dotless `ı` or a zero-width joiner. `record` adds
|
|
535
|
+
regex traps (those, the Kelvin sign, long s, Arabic-Indic digits, line separators, final sigma)
|
|
536
|
+
to every function in a file that uses regexes, but fuzz your real patterns against real text too.
|
|
537
|
+
- **What changes between runs.** `record` runs the original twice and sorts out what differed:
|
|
538
|
+
changed values (times, ids) become wildcards; the same lines in another order (hash maps,
|
|
539
|
+
concurrency) are compared in any order, so a port still has to produce exactly those lines; a
|
|
540
|
+
different number of lines becomes `...`, which matches anything. `record` lists each kind:
|
|
541
|
+
look at every one, since a hash-order or concurrency difference is exactly what can change for
|
|
542
|
+
real in a port.
|
|
543
|
+
- **Floats.** Number-to-text formatting differs between languages (`1e21`, `-0`, digit counts).
|
|
544
|
+
The traps include those values, and they must match exactly; `--float-tolerance` forgives
|
|
545
|
+
rounding only, never formatting.
|
|
546
|
+
- **Anything not in the output.** Timing, memory, concurrency under load, and side effects other
|
|
547
|
+
than stdout, stderr, exit codes, written files and HTTP responses (network calls, databases,
|
|
548
|
+
signals) are not compared.
|
|
549
|
+
- **Other platforms.** A recording proves behavior on the machine that ran it. C whose results
|
|
550
|
+
depend on type sizes, endianness or the compiler can behave differently on the target; `analyze`
|
|
551
|
+
keeps hardware-facing C in C for that reason.
|
|
552
|
+
|
|
472
553
|
## FAQ
|
|
473
554
|
|
|
474
555
|
**Does it rewrite my code automatically?** No. It finds what to move, generates the bridge,
|
|
@@ -481,7 +562,46 @@ runs both and returns the original's result while you build confidence).
|
|
|
481
562
|
**Is Rust always faster?** No, and rust-anything says so. A small function called once per item
|
|
482
563
|
is often slower in Rust, because each call crosses a bridge; V8, the JVM and Go run such functions
|
|
483
564
|
in nanoseconds. `profile` finds the loop around it, `--batch` moves the whole loop, and `bench`
|
|
484
|
-
gives a verdict before you ship.
|
|
565
|
+
gives a verdict before you ship. Code already compiled by numba, Cython or JAX runs as machine
|
|
566
|
+
code too: `profile` and `analyze` flag it, since porting it buys little speed.
|
|
567
|
+
|
|
568
|
+
**My code is numeric; will the floats match exactly?** Often not: operation order, fused
|
|
569
|
+
multiply-add and the math library differ between compilers. Record with `--float-tolerance 1e-9`
|
|
570
|
+
(`record` or `app record`), and floats match within that share of the larger value (absolute below
|
|
571
|
+
1). Integers, text and structure still have to match exactly.
|
|
572
|
+
|
|
573
|
+
**Can it port an app I only have as an APK, a JAR or an .exe?** No. It ports source code: it
|
|
574
|
+
parses the functions, records what each one does, and checks the Rust against the running
|
|
575
|
+
original. A compiled app has none of that to work with, and `analyze` says so. Writing a new Rust
|
|
576
|
+
app from a binary's visible behavior is a different project.
|
|
577
|
+
|
|
578
|
+
**Should I port battle-tested C?** Often not, and `analyze` tells you where. C that touches
|
|
579
|
+
hardware registers, relies on its compiler's type sizes or memory layout, or uses inline assembly
|
|
580
|
+
(`volatile`, bitfields, packed structs, `__asm__`, integers cast to addresses) is marked "keep in
|
|
581
|
+
C": a recording on your machine proves nothing about the target, and stable driver or firmware
|
|
582
|
+
code gains little from a rewrite. The portable logic around it (parsing, protocols, data handling)
|
|
583
|
+
is what moves well.
|
|
584
|
+
|
|
585
|
+
**Can it port my Electron app?** The logic, yes; the windows stay web pages. `analyze
|
|
586
|
+
--whole-app` spots Electron and plans the main process piece by piece while the renderer stays as
|
|
587
|
+
it is. Moving the UI to Tauri (the same web UI on a Rust backend) is a separate step once the logic
|
|
588
|
+
is Rust.
|
|
589
|
+
|
|
590
|
+
**What about C#, Kotlin or Swift?** C# is in preview (see [Languages](#languages)); Kotlin and
|
|
591
|
+
Swift are not supported yet. Each language needs a parser, a recorder, a bridge and a replay
|
|
592
|
+
driver, all tested end to end. Open an issue (or upvote one) for the language you need.
|
|
593
|
+
|
|
594
|
+
**Won't the Rust be much bigger than the original?** It shouldn't be. `gate` compares the port's
|
|
595
|
+
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
|
|
596
|
+
does, or handling cases one by one. `analyze` lists the crates to use.
|
|
597
|
+
|
|
598
|
+
**Doesn't porting piece by piece lock the Rust into the old app's design?** Only while both run
|
|
599
|
+
side by side. The recordings check behavior at the app's edges (a CLI's output, a server's
|
|
600
|
+
responses, a module's exported functions), not its internals. Mirror the old structure while
|
|
601
|
+
units still cross the bridge; once `app lift` has removed the original, restructure the Rust
|
|
602
|
+
freely, and `app replay` still proves the behavior. Nothing calls back into the original either:
|
|
603
|
+
the front door runs it as a separate process (or forwards HTTP to it), bridged units are called
|
|
604
|
+
by the original and never the other way round, and callbacks stay in the source language.
|
|
485
605
|
|
|
486
606
|
**Does my code leave my machine?** No: rust-anything runs locally and sends none of your code
|
|
487
607
|
anywhere. Cargo downloads crates as usual, and your agent's model provider sees what your agent
|
|
@@ -501,4 +621,4 @@ especially welcome.
|
|
|
501
621
|
|
|
502
622
|
## License
|
|
503
623
|
|
|
504
|
-
[MIT](./LICENSE). Ports and generated code in your repository are yours.
|
|
624
|
+
[MIT](./LICENSE) © [Erkam Yaman](https://github.com/erkamyaman). Ports and generated code in your repository are yours.
|
package/bin/rust-anything.js
CHANGED
|
@@ -10,7 +10,7 @@ const bin = path.join(__dirname, '..', 'binaries', key, exe)
|
|
|
10
10
|
if (!fs.existsSync(bin)) {
|
|
11
11
|
console.error(
|
|
12
12
|
`rust-anything: no prebuilt binary for ${key}.\n` +
|
|
13
|
-
'Install it with Cargo instead: cargo install
|
|
13
|
+
'Install it with Cargo instead: cargo install rust-anything',
|
|
14
14
|
)
|
|
15
15
|
process.exit(1)
|
|
16
16
|
}
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rust-anything",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Rewrite your app in Rust, one piece at a time,
|
|
3
|
+
"version": "1.3.0",
|
|
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",
|
|
7
7
|
"performance",
|