rust-anything 1.0.1 → 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/README.md
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="docs/assets/hero.png" alt="rust-anything:
|
|
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
3
|
</p>
|
|
4
4
|
|
|
5
|
-
**
|
|
6
|
-
Python, C, Go, Ruby and Java
|
|
7
|
-
behavior.
|
|
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:
|
|
8
9
|
|
|
9
10
|
| Real workload, same results as the original | Original | With rust-anything |
|
|
10
11
|
| --- | ---: | ---: |
|
|
@@ -56,6 +57,7 @@ must be on your `PATH`):
|
|
|
56
57
|
reads skills. It keeps your other settings, is safe to run again, and `--remove` undoes it.
|
|
57
58
|
Then ask your agent, for example:
|
|
58
59
|
|
|
60
|
+
- *"Rewrite this CLI in Rust with rust-anything, end to end, and prove it behaves the same."*
|
|
59
61
|
- *"This search feels slow. Profile it with rust-anything and move the hot loop to Rust."*
|
|
60
62
|
- *"Plan a migration of `src/parser/` to Rust with rust-anything; port the first unit and prove it."*
|
|
61
63
|
- *"Bench the Rust port in `rust/text-rs` against the original and tell me whether to ship it."*
|
|
@@ -127,21 +129,166 @@ The original stays the source of truth: `record` runs it on edge cases (and your
|
|
|
127
129
|
saves what it returns or throws; `diff` replays every case against the Rust; nothing ships until
|
|
128
130
|
they all match and `gate` passes. Callers keep the original API throughout.
|
|
129
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
|
+
|
|
130
142
|
## The loop
|
|
131
143
|
|
|
132
144
|
| Step | Command | What it does |
|
|
133
145
|
| --- | --- | --- |
|
|
134
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 |
|
|
135
|
-
| 1. Plan | `rust-anything analyze <repo>` | Units, port order, risks with `file:line`, bridge per unit, dependency-to-crate fit, best first ports |
|
|
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 |
|
|
136
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 |
|
|
137
|
-
| 3. Record | `rust-anything record <crate>` | Runs the original on generated edge cases (non-ASCII, emoji, `-0`, `NaN`, ints where floats are expected, ...) and saves `cases.jsonl` |
|
|
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` |
|
|
138
150
|
| 3. Build | `rust-anything build <crate>` | Builds the Rust side: `.node`, wasm package, Python extension or shared library |
|
|
139
151
|
| 3. Diff | `rust-anything diff <crate>` | Replays the recorded cases against Rust, called the way the original's callers call it; lists mismatches |
|
|
140
152
|
| 3. Bench | `rust-anything bench <crate>` | Times the recorded cases on the original and on Rust, bridge included |
|
|
141
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` |
|
|
142
|
-
| 5. Gate | `rust-anything gate <crate>` | fmt, clippy `-D warnings`, tests, `unsafe` audit, nothing unported, build, API, behavior |
|
|
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 |
|
|
143
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 |
|
|
144
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
|
+
|
|
145
292
|
## Case study: x18n's core
|
|
146
293
|
|
|
147
294
|
All 29 functions of x18n's core that can move without an API change were ported with rust-anything:
|
|
@@ -301,7 +448,7 @@ installed, and TS that needs transforming (enums, parameter properties) is retri
|
|
|
301
448
|
## Development
|
|
302
449
|
|
|
303
450
|
```sh
|
|
304
|
-
cargo test # unit tests, fixture repo, record/diff/shadow loop (needs node)
|
|
451
|
+
cargo test # unit tests, fixture repo, record/diff/shadow loop (needs node), app record/replay per language
|
|
305
452
|
cargo clippy --all-targets -- -D warnings
|
|
306
453
|
cargo fmt
|
|
307
454
|
```
|
|
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.0
|
|
4
|
-
"description": "
|
|
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
5
|
"keywords": [
|
|
6
6
|
"rust",
|
|
7
7
|
"performance",
|