rust-anything 0.0.0-stage → 1.1.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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 the rust-anything authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,504 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <img src="docs/assets/hero.png" alt="rust-anything: Rewrite anything in Rust. Keep it working the whole way. Piece by piece, checked against the original at every step, until it is pure Rust." width="820">
3
+ </p>
2
4
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
5
+ **Rewrite your app in Rust, one piece at a time, proving nothing changed.** For TypeScript/JavaScript,
6
+ Python, C, Go, Ruby and Java apps: rust-anything ports your app piece by piece, checks every step
7
+ against the original's recorded behavior, and hands you a pure Rust app. Only need the slow part
8
+ fast? Port just that, one hot path at a time:
9
+
10
+ | Real workload, same results as the original | Original | With rust-anything |
11
+ | --- | ---: | ---: |
12
+ | x18n's sidebar search, 50,000 keys (TypeScript, Node) | 10 ms per query | **0.5 ms: 20x faster** |
13
+ | The same search in the browser (wasm, one thread) | 10 ms | **0.95 ms: 11.5x** |
14
+ | `slugify` over 20,000 strings (Python) | 98 ms | **17x faster** |
15
+ | `Shellwords.shellescape` from Ruby's standard library, 50,000 values | 88 ms | **11.8x faster** |
16
+ | `Slugify` over 50,000 strings (Go) | 49 ms | **4x faster** |
17
+ | `slugify` over 50,000 strings (Java) | 43 ms | **3x faster** |
18
+
19
+ <p align="center">
20
+ <img src="docs/assets/race.gif" alt="Typing user.profile into x18n's search over 50,000 keys: TypeScript spends 143 ms, the rust-anything batch 6.9 ms, with the same results at every keystroke." width="820">
21
+ </p>
22
+
23
+ Measured on 4 cores; every number has a benchmark in [`demo/`](./demo) that first checks the
24
+ results are identical. Calling Rust once per small function is usually *slower* than a JIT;
25
+ rust-anything finds the loop worth moving, and moves it.
26
+
27
+ > rust-anything is an independent project, not affiliated with or endorsed by the Rust Project
28
+ > or the Rust Foundation. "Rust" is a trademark of the Rust Foundation.
29
+
30
+ ## Quick start
31
+
32
+ Paste this into Claude Code, Codex, Cursor or Gemini CLI and let your agent install it:
33
+
34
+ ```text
35
+ Install rust-anything: run `cargo install --git https://github.com/erkamyaman/rust-anything`,
36
+ then `rust-anything setup`. Tell me when to restart you.
37
+ ```
38
+
39
+ Or yourself:
40
+
41
+ ```sh
42
+ npm install -g rust-anything # prebuilt binary for macOS, Linux and Windows
43
+ # or: cargo install --git https://github.com/erkamyaman/rust-anything
44
+ rust-anything setup # registers it with Claude Code, Codex, Cursor and Gemini CLI
45
+ ```
46
+
47
+ Prebuilt binaries are also attached to each [GitHub release](https://github.com/erkamyaman/rust-anything/releases).
48
+
49
+ In Claude Code you can also install it as a plugin (the MCP server and the skill; the CLI above
50
+ must be on your `PATH`):
51
+
52
+ ```text
53
+ /plugin install rust-anything --marketplace erkamyaman/rust-anything
54
+ ```
55
+
56
+ `setup` adds the MCP server to each agent it finds and installs the workflow skill where the agent
57
+ reads skills. It keeps your other settings, is safe to run again, and `--remove` undoes it.
58
+ Then ask your agent, for example:
59
+
60
+ - *"Rewrite this CLI in Rust with rust-anything, end to end, and prove it behaves the same."*
61
+ - *"This search feels slow. Profile it with rust-anything and move the hot loop to Rust."*
62
+ - *"Plan a migration of `src/parser/` to Rust with rust-anything; port the first unit and prove it."*
63
+ - *"Bench the Rust port in `rust/text-rs` against the original and tell me whether to ship it."*
64
+
65
+ ### Works with
66
+
67
+ | Agent | `rust-anything setup` adds |
68
+ | --- | --- |
69
+ | Claude Code | MCP server in `~/.claude.json`, skill in `~/.claude/skills/` |
70
+ | Codex | MCP server in `~/.codex/config.toml`, skill in `~/.codex/skills/` |
71
+ | Cursor | MCP server in `~/.cursor/mcp.json` |
72
+ | Gemini CLI | MCP server in `~/.gemini/settings.json` |
73
+ | Any other MCP client | add `rust-anything mcp` as a stdio server by hand (see [Install](#install)) |
74
+
75
+ Before changing a file that exists, `setup` saves a copy beside it (`<file>.rust-anything.bak`).
76
+
77
+ Or run the steps yourself:
78
+
79
+ <p align="center">
80
+ <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">
81
+ </p>
82
+
83
+
84
+ ```sh
85
+ rust-anything profile . -- node bench.mjs # what is hot, and who calls it
86
+ rust-anything bridge . src/fuzzy.ts --batch fuzzyScore:text
87
+ # write src/port.rs (or let your agent), then:
88
+ rust-anything record rust/fuzzy-rs && rust-anything build rust/fuzzy-rs
89
+ rust-anything diff rust/fuzzy-rs # every recorded case must match
90
+ rust-anything bench rust/fuzzy-rs # faster? the verdict says
91
+ rust-anything gate rust/fuzzy-rs # done means this passes
92
+ ```
93
+
94
+ rust-anything does not translate code: your coding agent (Claude Code, Codex, Cursor, ...) or you write
95
+ the Rust. rust-anything supplies what an agent cannot guess reliably: where the time goes, what to port
96
+ first and in which order, a bridge so the rest of the code calls the Rust with its API unchanged,
97
+ the exact behavior the port must match, a safe way to ship it, and a gate that says when a port is
98
+ done.
99
+
100
+ ## Languages
101
+
102
+ | Language | Unit | Bridge | Recorded and replayed by |
103
+ | --- | --- | --- | --- |
104
+ | TypeScript/JavaScript | folder or file | napi-rs or wasm-bindgen with a generated binary wire; classes and async included | Node, running the `.ts` sources |
105
+ | Python | package or module | PyO3 (abi3), direct conversion, typed exceptions | Python, importing the original |
106
+ | C | `.c` file | `extern "C"` functions with the original names and a header | the original compiled to a shared library, called through ctypes, one fork per case |
107
+ | 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
+ | Ruby | file or folder of module functions | a magnus extension under the original modules | a generated Ruby driver |
109
+ | Java | package of `public static` methods | typed JNI and a generated binary wire, in wrapper classes with the original methods | a generated reflection driver |
110
+
111
+ Every language except C also gets batch classes (`--batch`): the items cross once and stay in
112
+ Rust, and each call runs over all of them on all cores.
113
+
114
+ The language is detected from the repository (`go.mod`, `pom.xml`, `pyproject.toml`, `Gemfile`,
115
+ `package.json`, else the most common source files); `--lang` overrides it. Types come from the
116
+ source: TS types, Python hints, C and Go and Java signatures, Ruby YARD tags; untyped parameters
117
+ used as numbers are inferred as numbers.
118
+
119
+ ## How it works
120
+
121
+ ```
122
+ profile ──> analyze ──> bridge ──> record ──> port.rs ──> diff ──> bench ──> shadow ──> gate
123
+ where the what to the Rust what the you or every faster? both side done means
124
+ time goes port first crate and original your agent recorded the by side in this passes
125
+ wrapper does write it case verdict production
126
+ ```
127
+
128
+ The original stays the source of truth: `record` runs it on edge cases (and your own inputs) and
129
+ saves what it returns or throws; `diff` replays every case against the Rust; nothing ships until
130
+ they all match and `gate` passes. Callers keep the original API throughout.
131
+
132
+ A whole app goes through the same loop unit by unit, inside a frame that proves the whole
133
+ program ([Port a whole app](#port-a-whole-app)):
134
+
135
+ ```
136
+ analyze --whole-app ──> app record ──> app front-door ──> per unit: the loop above, then app wire ──> app lift
137
+ shape, every what the app Rust owns the gate passes, so the unit answers in pure Rust,
138
+ dependency, the does from the entry point; the Rust: replay 100%, fallback rate down proved by
139
+ decisions to make outside original answers replay
140
+ ```
141
+
142
+ ## The loop
143
+
144
+ | Step | Command | What it does |
145
+ | --- | --- | --- |
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 |
147
+ | 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
+ | 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` |
150
+ | 3. Build | `rust-anything build <crate>` | Builds the Rust side: `.node`, wasm package, Python extension or shared library |
151
+ | 3. Diff | `rust-anything diff <crate>` | Replays the recorded cases against Rust, called the way the original's callers call it; lists mismatches |
152
+ | 3. Bench | `rust-anything bench <crate>` | Times the recorded cases on the original and on Rust, bridge included |
153
+ | 4. Shadow | `rust-anything shadow <crate>` | Drop-in that runs both, returns the original's result, reports mismatches; `RUST_ANYTHING_MODE=old\|shadow\|new` |
154
+ | 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 |
155
+ | 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 |
156
+
157
+ ## Port a whole app
158
+
159
+ The goal is a pure Rust app that behaves like the original, with the original kept as reference.
160
+ Your agent writes the Rust; rust-anything orders the work, scaffolds it, and proves every step.
161
+ The [whole-app skill](./skills/rust-anything/whole-app.md) walks the agent through it, starting
162
+ with the decisions only you can make.
163
+
164
+ Plan first: `rust-anything analyze . --whole-app` adds the app's shape (CLI, server or library)
165
+ and entry points, every external dependency (imported or declared) with its Rust crate and fit,
166
+ the port order as pieces (units that import each other move together), and numbered decisions
167
+ with a recommended answer: keep units, blocked units, dependencies with no or a partial crate.
168
+
169
+ Then prove the whole program from the outside. `record` and `diff` prove one unit; `app record`
170
+ and `app replay` prove the app, for CLIs and servers in any of the six languages (the app is a
171
+ black box):
172
+
173
+ ```sh
174
+ rust-anything app record . -- python3 cli.py # the command that runs the original
175
+ rust-anything app replay . # the original must pass 100%
176
+ rust-anything app replay . --build "target/release/mytool"
177
+ ```
178
+
179
+ - `app record` runs the original on the app's own documented examples (`$ mytool ...` lines in
180
+ its Markdown and shell files, with the files they name), an `--inputs` JSONL file
181
+ (`{"name", "args", "stdin", "env", "files"}`), and semantic traps derived from those cases
182
+ (non-ASCII and emoji strings, negative division and modulo, overflow, large and tiny floats,
183
+ map order, missing files). Each case runs twice; what differs between the two runs becomes a
184
+ `[..]` wildcard. `--normalize timestamps|uuids|key-order` or `--normalize name=regex` adds
185
+ normalizers, saved with the cases.
186
+ - Cases are [trycmd](https://docs.rs/trycmd) files in `rust/app-cases/`: `<case>.toml` (argv, env,
187
+ exit code), `.stdin`, `.stdout`, `.stderr`, `.in/` (files in) and `.out/` (files written). Read
188
+ and edit them by hand; a Rust test can run them with `trycmd` once the port has a binary.
189
+ - `app replay` runs any build against the cases, prints `passed/total`, writes
190
+ `rust/app-cases/replay-report.md` with a diff per failing case, and exits non-zero on any
191
+ mismatch. A build that appends to the file named by `RUST_ANYTHING_FALLBACK_LOG` (one line per
192
+ fallback to the original), as the front door below does, also gets its fallback rate reported.
193
+
194
+ Then move the entry point to Rust and hand it commands one unit at a time:
195
+
196
+ ```sh
197
+ rust-anything app front-door . # rust/app: every command runs the original
198
+ rust-anything app wire . textkit --command upper # after textkit-rs passes gate
199
+ # write the glue in rust/app/src/units/textkit.rs, then:
200
+ rust-anything app wire . textkit # 100% again, lower fallback rate
201
+ ```
202
+
203
+ - `app front-door` scaffolds `rust/app`, a Rust binary named after the app: a clap parser for the
204
+ commands and flags in the recorded cases, where every command runs the original with the same
205
+ argv, stdin and environment and passes its output and exit code through. Each fallback is
206
+ counted, so replaying the fresh front door gives 100% passed at 100% fallback (it builds and
207
+ replays to show it). It never overwrites `rust/app`: the code is yours from then on.
208
+ - `app wire <repo> <unit> --command <name>` runs `gate` on the unit crate (`--skip-gate` if it just
209
+ passed), adds it to `rust/app` as a library, writes `src/units/<unit>.rs` once for you or your
210
+ agent to fill in (parse the arguments, call `<crate>::port`, print what the original prints),
211
+ routes the commands to it, then builds and replays. `RUST_ANYTHING_UNIT_<NAME>=original` sends a
212
+ wired unit back to the original until the lift.
213
+
214
+ Wire the app's own name as a command (`--command mytool`) for argv that names no command: no
215
+ arguments, unknown commands, usage errors.
216
+
217
+ When replay passes with fallback rate 0 and every unit passes gate, make it a pure Rust app:
218
+
219
+ ```sh
220
+ rust-anything app lift .
221
+ ```
222
+
223
+ - `app lift` refuses until both hold, and says what blocks it: the cases still falling back,
224
+ glue still a stub, units failing gate.
225
+ - On a copy first, it removes the fallback path and the kill switches, turns each unit crate into
226
+ a plain library of `rust/app` (no `cdylib`, bindings or generated wrappers), and adds
227
+ `rust/app/tests/app_cases.rs`, which runs `rust/app-cases` with trycmd on `cargo test`, so CI
228
+ needs nothing but cargo.
229
+ - Then it runs the lift checklist: fmt, clippy `-D warnings` and tests on every unit and on
230
+ `rust/app`, every target named in `rust/DECISIONS.md` built or checked where it is installed,
231
+ files read at run time and asset folders not embedded, and replay on the pure binary. Only when
232
+ all of it passes are the changes written back. The original is never touched.
233
+
234
+ ### Servers
235
+
236
+ The same commands prove HTTP servers. `--http` says the command starts a server; it takes its
237
+ port from `PORT` or `{port}` in the command (`--port` for one that always listens on the same
238
+ port):
239
+
240
+ ```sh
241
+ rust-anything app record . --http -- node server.js
242
+ rust-anything app replay .
243
+ rust-anything app front-door . # axum: every route proxied
244
+ rust-anything app wire . api --route 'GET /users/{id}' --route '*'
245
+ rust-anything app lift .
246
+ ```
247
+
248
+ - Requests come from `curl` lines in the app's docs (`curl -X POST -d ... http://localhost:8080/x`),
249
+ `--inputs` (`{"name", "method", "path", "headers", "body"}`) and traps: path segments and query
250
+ values swapped for the same traps as CLI arguments, bodies for text and JSON traps, and an
251
+ unknown route. Each run starts the server fresh and sends the requests in name order, so state
252
+ between requests is kept.
253
+ - Cases are `rust/app-cases/http/<case>.toml` (the request, the status and the headers that matter)
254
+ and `<case>.body` (the response body, with `[..]` where two runs differed). Date, server and
255
+ other per-response headers are left out; delete any header line you do not care about.
256
+ - The front door is an axum server that starts the original on a port of its own and proxies
257
+ every route no unit answers. `wire --route` takes axum routes: `METHOD /path/{param}`, `/path`
258
+ for any method, `*` for everything else; the glue gets the route, its parameters and the
259
+ request. `lift` removes the proxy; HTTP cases then run in CI with `app replay`.
260
+
261
+ ### Libraries
262
+
263
+ A library has no process to replay: its public API is the front door, and each unit's recorded
264
+ cases are the proof.
265
+
266
+ ```sh
267
+ rust-anything app front-door . # rust/app: a Rust crate with the public API
268
+ # each unit through the loop: bridge, record, port.rs, build, diff, gate; then:
269
+ rust-anything app wire . textkit-rs # re-exported from rust/app; the original imports its shadow
270
+ rust-anything app replay . # every wired unit's cases; fallback = exports still in the original
271
+ rust-anything app lift .
272
+ ```
273
+
274
+ - `app front-door` finds the public API (every unit's exports) when the repository has no `main`
275
+ and no server (`--library` otherwise), and scaffolds `rust/app` as a library crate. Each wired
276
+ unit becomes a module of it: `pub use textkit_rs::port as textkit;`.
277
+ - `app wire` takes a crate made by `bridge`, runs `gate`, and writes the unit's shadow drop-in:
278
+ the original package imports it in place of the unit, so its callers keep the original API and
279
+ reach the Rust. `RUST_ANYTHING_UNIT_<NAME>=original` sends the unit back (C: build without the
280
+ shadow's flags).
281
+ - `app replay` runs every wired unit's recorded cases through its bindings. The fallback rate is
282
+ the share of public exports Rust does not answer yet: unwired units, and exports `bridge` keeps
283
+ in the original language.
284
+ - `app lift` needs fallback 0 and every unit through `gate`; it strips the bindings, wrappers and
285
+ shadows from the units and leaves `rust/app` as one pure Rust library. It does not touch any
286
+ `port.rs`, so the cases that matched through the bindings still describe it; the checklist
287
+ warns about files of the original that still import the shadows.
288
+
289
+ All five are MCP tools too: `app_record`, `app_replay`, `app_front_door`, `app_wire` and
290
+ `app_lift`.
291
+
292
+ ## Case study: x18n's core
293
+
294
+ All 29 functions of x18n's core that can move without an API change were ported with rust-anything:
295
+ every gate passes and 7,925 recorded cases match exactly. `rust-anything bench` then showed the ports
296
+ are slower than the TS as called from JS, because the bridge costs more than the work. Full report:
297
+ [`demo/x18n-core`](./demo/x18n-core/README.md). The lesson is built in: measure with `bench` before
298
+ shipping a port.
299
+
300
+ ## Hot paths: keep the data in Rust
301
+
302
+ A port called once per item pays the bridge once per item, and loses to a JIT. What wins is
303
+ moving the loop: `profile` finds it, and `--batch` generates a class that takes the items once
304
+ and runs the function over all of them per call, on all cores, with typed-array results.
305
+
306
+ ```sh
307
+ rust-anything profile ../x18n -- node --experimental-strip-types $PWD/demo/x18n-search/search.ts .
308
+ # -> fuzzyScore: a quarter of the run, called per key by `matched`: batch it
309
+ rust-anything bridge ../x18n packages/core/src/fuzzy.ts --batch fuzzyScore:text
310
+ ```
311
+
312
+ ```js
313
+ const search = new FuzzyScoreBatch(keys) // once
314
+ const order = search.rank(query, 0) // per keystroke: indexes, best first
315
+ ```
316
+
317
+ A `FuzzyScoreIndex` struct in `port.rs` replaces the default loop with one that prepares the
318
+ items once, and can rank by itself (`rank`): it keeps the keys lowercased with a character mask
319
+ each, a table of each key's first position of every common character (a one-letter query is one
320
+ column), and the last query's matches (typing `se` after `s` rescores only what `s` matched). On
321
+ x18n's sidebar search over 50,000 keys, typed letter by letter, with identical results:
322
+
323
+ | | Per query | vs TS |
324
+ | --- | ---: | ---: |
325
+ | TS: `map(fuzzyScore)`, filter, sort | 10 ms | 1x |
326
+ | TS with the same narrowing as the index | 4.1-5.4 ms | 2x |
327
+ | The same port, called per key | - | 0.2-0.4x |
328
+ | `FuzzyScoreBatch`, default index (4 cores) | 5.1 ms | 1.7x |
329
+ | `FuzzyScoreBatch` with `FuzzyScoreIndex` (napi, 4 cores) | 0.45-0.56 ms | **18-22x** |
330
+ | The same with wasm (one thread) | 0.95 ms | **11.5x** |
331
+
332
+ Against TS doing the same narrowing, Rust is still 7-12x faster (wasm 5x). Turn the returned
333
+ indexes into keys with a plain loop: `Array.from(order, i => keys[i])` cost 20x more, 0.4 ms.
334
+
335
+ Every language gets batches, and they beat the original even where per-call ports lose. The
336
+ same work on 4 cores, identical results and errors (benchmarks in each demo folder):
337
+
338
+ | Language | Workload | Original | Per-call port vs original | Batch vs original |
339
+ | --- | --- | ---: | ---: | ---: |
340
+ | TS | x18n search, 50,000 keys | 10 ms | 0.2-0.4x | **20x** |
341
+ | Python | `slugify`, 20,000 strings | 98 ms | - | **17x** |
342
+ | Ruby | `slugify`, 20,000 strings | 110 ms | - | **12.7x** |
343
+ | Ruby | `shellescape` (stdlib), 50,000 mixed values | 88 ms | - | **11.8x** |
344
+ | Go | `Slugify`, 50,000 strings | 49 ms | 0.93x | **4x** |
345
+ | Java | `slugify`, 50,000 strings | 43 ms | 0.68x | **3x** |
346
+
347
+ Compiled originals gain less: the per-item work is already fast, so the batch wins by the number of
348
+ cores. Batch crates allocate with mimalloc: with the system allocator the Go batch was slower than
349
+ one thread. Demo: [`demo/x18n-search`](./demo/x18n-search/README.md).
350
+
351
+ ## Real code in six languages
352
+
353
+ Go's `path`, Ruby's `shellwords`, Python's `colorsys`, JDK and glibc behavior behind small
354
+ facades: every port passes its gate, 13,010 recorded cases in all. The runs found and fixed
355
+ bugs in rust-anything (floats off by one ULP through `serde_json`, C crashes during recording,
356
+ untyped code getting garbage inputs). Called per function, the Ruby port runs 4.4x faster than
357
+ Ruby and the Python port 1.35x faster than CPython, while Go and Java leaf functions stay faster
358
+ in their own language; as batches, all of them win (see the table above).
359
+ Report: [`docs/real-world-languages.md`](./docs/real-world-languages.md).
360
+
361
+ ## Example: a real module from x18n
362
+
363
+ `packages/core/src/fuzzy.ts` from [x18n](https://github.com/x18n-dev/x18n), ported both ways in
364
+ [`demo/`](./demo):
365
+
366
+ ```sh
367
+ rust-anything analyze ../x18n # fuzzy.ts: ready, wasm-bindgen (core runs in browsers)
368
+ rust-anything bridge ../x18n packages/core/src/fuzzy.ts --out demo/fuzzy-rs
369
+ rust-anything record demo/fuzzy-rs --count 2000
370
+ # write src/port.rs
371
+ rust-anything gate demo/fuzzy-rs
372
+ ```
373
+
374
+ A first port that indexed by Rust `char` passed simple tests but failed `diff`:
375
+
376
+ ```
377
+ 198/200 cases match
378
+ - fuzzyScore("b😀", "a😀b😀c"): expected {"ok":1997}, got {"ok":1998}
379
+ ```
380
+
381
+ JS `indexOf` counts UTF-16 code units, so an emoji is two positions. The port in
382
+ `demo/*/src/port.rs` uses the generated `utf16` helpers and passes 2000/2000 cases and the gate,
383
+ as napi-rs (`demo/fuzzy-napi`) and as wasm-bindgen (`demo/fuzzy-rs`).
384
+
385
+ The plan rust-anything writes for all of x18n: [`docs/examples/x18n.md`](./docs/examples/x18n.md).
386
+
387
+ ## Install
388
+
389
+ ```sh
390
+ cargo install --path .
391
+ ```
392
+
393
+ `record`, `diff` and `bench` run the original in its own runtime: Node 22.6+ for TS (it runs `.ts`
394
+ sources directly), Python 3.9+ for Python and C (ctypes), Go 1.21+, Ruby 3+, JDK 17+
395
+ (`javac` and `java`). C also needs a C compiler. wasm bridges also need `rustup target add wasm32-unknown-unknown` and
396
+ `cargo install wasm-bindgen-cli --version <the crate's wasm-bindgen version> --locked`; `build` names
397
+ the exact version.
398
+
399
+ For agents, `rust-anything setup` registers everything (see Quick start). To add the MCP server to
400
+ one project by hand instead (`.mcp.json`):
401
+
402
+ ```json
403
+ { "mcpServers": { "rust-anything": { "command": "rust-anything", "args": ["mcp"] } } }
404
+ ```
405
+
406
+ ## What `bridge` decides
407
+
408
+ - Exports that cannot cross a bridge stay in the source language, with the reason, and the shadow
409
+ module re-exports the original. For TS:
410
+ functions that take or return functions, generators and iterators, RegExp, `instanceof` checks,
411
+ generics, and values whose types (followed through imports, re-exports and `extends`) hold
412
+ functions. `--keep "name: reason"` keeps more, e.g. code that depends on `Intl` data.
413
+ - TS types map to Rust types, with type aliases resolved through imports and parameter types
414
+ inferred from default values; structured values cross as a generated binary wire (JSON only
415
+ as a fallback for shapes the wire does not model).
416
+ - JSON cannot express `undefined`, NaN, Infinity, -0 or lone surrogates: structured values carry
417
+ markers (`{"$undefined": true}`, `{"$num": "NaN"}`, `{"$utf16": [...]}`) that the generated
418
+ `index.cjs` translates, with helpers in the crate's `js.rs`.
419
+
420
+ `record` runs TS sources as they are: a Node resolve hook follows bundler-style imports
421
+ (`./errors` to `./errors.ts`), `--resolve-from` supplies npm packages when the repo has none
422
+ installed, and TS that needs transforming (enums, parameter properties) is retried with
423
+ `--experimental-transform-types`.
424
+
425
+ ## What `analyze` looks at
426
+
427
+ - Packages (`package.json`) and source files; skips `node_modules`, build output, fixtures,
428
+ playgrounds, tool configs. Vue/Svelte/Astro `<script>` blocks are parsed for imports.
429
+ - **Units**: a folder of source files, or a file at a package's source root.
430
+ - **Waves**: a unit's imports come in earlier waves; import cycles are ported together.
431
+ - **Bridge**: napi-rs when the unit or anything it imports needs Node; wasm-bindgen for portable
432
+ code; keep in JS for UI and editor code.
433
+ - **Readiness** (how safe) and **priority** (safe and worth it: loops and string work, tests, size).
434
+
435
+ | Risk | Severity | Example |
436
+ | --- | --- | --- |
437
+ | String offsets | high | `slice`, `indexOf`, `matchAll`, the `d` flag: UTF-16 vs UTF-8 |
438
+ | Regex syntax | high | lookaround, backreferences, `y`: not in the `regex` crate |
439
+ | Dynamic regex | high | `new RegExp(userPattern)`: JS syntax at runtime |
440
+ | Dynamic code | high | `eval`, `new Function`, computed `import()` |
441
+ | Dynamic typing | medium | `any`, `'key' in value` |
442
+ | Ordered collections | medium | `Map`, `Set`, `Object.keys`: insertion order |
443
+ | Async, generators | medium | promise and generator boundaries |
444
+ | Class inheritance, reflection | medium | `extends`, `Proxy`, `Reflect`, `Symbol` |
445
+ | Callback-shaped APIs | medium | function-typed params and methods: chatty bridges |
446
+ | Exceptions, numbers, JSON | low | `throw`, bitwise ops, `JSON.stringify` order |
447
+
448
+ ## Development
449
+
450
+ ```sh
451
+ cargo test # unit tests, fixture repo, record/diff/shadow loop (needs node), app record/replay per language
452
+ cargo clippy --all-targets -- -D warnings
453
+ cargo fmt
454
+ ```
455
+
456
+ Design choices and their reasons: [DECISIONS.md](./DECISIONS.md).
457
+
458
+
459
+ ## Update or remove
460
+
461
+ ```sh
462
+ npm install -g rust-anything@latest # update (npm)
463
+ cargo install --git https://github.com/erkamyaman/rust-anything --force # update (Cargo)
464
+ rust-anything setup # refresh agent settings
465
+ rust-anything setup --remove && npm uninstall -g rust-anything # remove (npm)
466
+ rust-anything setup --remove && cargo uninstall rust-anything # remove (Cargo)
467
+ ```
468
+
469
+ `setup --remove` takes out only rust-anything's entries; the copies it saved
470
+ (`<file>.rust-anything.bak`) stay until you delete them.
471
+
472
+ ## FAQ
473
+
474
+ **Does it rewrite my code automatically?** No. It finds what to move, generates the bridge,
475
+ records what the original does and checks the Rust against it. You or your agent write the Rust
476
+ in `port.rs`; `diff` and `gate` decide when it is right.
477
+
478
+ **Will my app's API change?** No. Callers import the same functions (or the shadow module, which
479
+ runs both and returns the original's result while you build confidence).
480
+
481
+ **Is Rust always faster?** No, and rust-anything says so. A small function called once per item
482
+ is often slower in Rust, because each call crosses a bridge; V8, the JVM and Go run such functions
483
+ in nanoseconds. `profile` finds the loop around it, `--batch` moves the whole loop, and `bench`
484
+ gives a verdict before you ship.
485
+
486
+ **Does my code leave my machine?** No: rust-anything runs locally and sends none of your code
487
+ anywhere. Cargo downloads crates as usual, and your agent's model provider sees what your agent
488
+ sends it, under its own policy.
489
+
490
+ **What does it need installed?** Rust, plus the runtime of the language you port (see
491
+ [Install](#install)).
492
+
493
+ **Something broke.** Open an issue with the command, its output and your platform.
494
+
495
+ ## Contributing
496
+
497
+ Issues and pull requests are welcome. Before a pull request: `cargo fmt`, `cargo clippy
498
+ --all-targets -- -D warnings` and `cargo test` must pass (see [Development](#development)); design
499
+ choices and their reasons are in [DECISIONS.md](./DECISIONS.md). Case studies of real ports are
500
+ especially welcome.
501
+
502
+ ## License
503
+
504
+ [MIT](./LICENSE). Ports and generated code in your repository are yours.
@@ -0,0 +1,26 @@
1
+ #!/usr/bin/env node
2
+ 'use strict'
3
+ const fs = require('node:fs')
4
+ const path = require('node:path')
5
+ const { spawnSync } = require('node:child_process')
6
+
7
+ const key = `${process.platform}-${process.arch}`
8
+ const exe = process.platform === 'win32' ? 'rust-anything.exe' : 'rust-anything'
9
+ const bin = path.join(__dirname, '..', 'binaries', key, exe)
10
+ if (!fs.existsSync(bin)) {
11
+ console.error(
12
+ `rust-anything: no prebuilt binary for ${key}.\n` +
13
+ 'Install it with Cargo instead: cargo install --git https://github.com/erkamyaman/rust-anything',
14
+ )
15
+ process.exit(1)
16
+ }
17
+
18
+ const result = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' })
19
+ if (result.error) {
20
+ console.error(`rust-anything: ${result.error.message}`)
21
+ process.exit(1)
22
+ }
23
+ if (result.signal) {
24
+ process.kill(process.pid, result.signal)
25
+ }
26
+ process.exit(result.status ?? 1)
Binary file
package/package.json CHANGED
@@ -1,6 +1,32 @@
1
1
  {
2
2
  "name": "rust-anything",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.1.0",
4
+ "description": "Rewrite your app in Rust, one piece at a time, proving nothing changed. TypeScript, Python, C, Go, Ruby, Java.",
5
+ "keywords": [
6
+ "rust",
7
+ "performance",
8
+ "migration",
9
+ "ffi",
10
+ "napi",
11
+ "pyo3",
12
+ "mcp",
13
+ "claude-code",
14
+ "codex"
15
+ ],
16
+ "license": "MIT",
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/erkamyaman/rust-anything.git"
20
+ },
21
+ "homepage": "https://github.com/erkamyaman/rust-anything",
22
+ "bin": {
23
+ "rust-anything": "bin/rust-anything.js"
24
+ },
25
+ "files": [
26
+ "bin",
27
+ "binaries"
28
+ ],
29
+ "engines": {
30
+ "node": ">=18"
31
+ }
32
+ }