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: Your app isn't slow. One loop is. rust-anything finds it, moves it to Rust, and proves nothing else changed." width="820">
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
- **Make the slow part of your app fast in Rust, without rewriting the app.** For TypeScript/JavaScript,
6
- Python, C, Go, Ruby and Java codebases, one hot path at a time, proven identical by recorded
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
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "rust-anything",
3
- "version": "1.0.1",
4
- "description": "Make the slow part of your app fast in Rust, without rewriting the app. TypeScript, Python, C, Go, Ruby, Java.",
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",