OPEN SOURCE DEEP DIVE
rust-anything: Verified Incremental Migration to Rust
Move production code to Rust one verified unit at a time with behavioral recordings, typed bridges, batch execution, shadow runs, and an app-level completion gate.
rust-anything is aimed at a harder problem than the familiar promise of translating a codebase into Rust in one pass: proving that each replacement preserves the behavior of the system it replaces. It supports TypeScript, JavaScript, Python, C, Go, Ruby, and Java, and works at two scales. A team can move only a measured hot path, or it can migrate a complete command-line application, HTTP server, or library through a controlled sequence that keeps the original runnable until the final cutover. Version 1.4.0 is MIT licensed and requires Rust 1.97 or newer.
The division of responsibility is essential. rust-anything does not generate the complete Rust implementation automatically. A developer or coding agent still writes port.rs. The tool provides the migration infrastructure around that work: profiling, unit ordering, bindings, behavior recording, replay, benchmarking, shadow execution, and a completion gate. It turns the question “is this Rust port ready?” into checks that can be rerun and audited.
Start with a measured boundary, not a total rewrite
When speed is the goal, rust-anything starts with a real workload rather than a language preference. Its profiler identifies the functions consuming time, their callers, and loops that can be moved as a batch. That distinction matters because calling a tiny Rust function once per item can be slower than leaving it inside V8, the JVM, or the Go runtime. The bridge may cost more than the function itself.
The tool therefore supports two useful strategies. A hot function can be moved together with its caller loop, reducing crossings. Alternatively, a generated batch interface can accept a large collection once, keep it in Rust, and process every item across multiple cores. Search, text normalization, parsing, and rule evaluation are natural candidates because they repeatedly operate on large collections.
The project reports large gains in its bundled examples, including roughly 20x for a 50,000-key TypeScript search and 17x for a Python string-normalization workload. Those figures come from the repository benchmarks and were not independently rerun for this article. The project is also explicit that Rust is not always faster. Its benchmark includes bridge cost and can recommend keeping a function in the original language.
A complete loop for one migration unit
Every unit follows a sequence with a concrete artifact and a stop condition. First, the tool profiles a representative workload. Next, it analyzes the repository to find units, dependencies, risk locations, bridge choices, and a safe port order. It then scaffolds a Rust crate, a wrapper for the original runtime, and stubs in port.rs. Before the Rust implementation is accepted, the original behavior is recorded and replayed against it.
- Profile: identify hot functions, callers, and loops worth batching.
- Plan: map units, risks, dependencies, bridge choices, and migration waves.
- Bridge: generate bindings that preserve the caller-facing API.
- Record: run the original on edge cases, supplied inputs, and semantic traps.
- Implement: write the Rust port manually or with a coding agent.
- Build and diff: load the generated artifact and replay every recorded case.
- Benchmark and shadow: include bridge cost and run both implementations side by side.
- Gate: require formatting, linting, tests, API coverage, error paths, and behavior to pass.
Recording supplies the ground truth. Generated cases include non-ASCII text, emoji, negative zero, NaN, integer and floating-point boundaries, plus traps for string length, case conversion, signed division, overflow, map order, and other semantic hazards. Teams can add production samples, regression cases, and existing test fixtures. A mismatch is treated as a port bug rather than a reason to edit the recording until it agrees with the new implementation.
Supported languages and bridges
The production-supported languages all use a native interoperability layer appropriate to their runtime. Language detection normally follows project manifests and source layout, with an explicit override available. PHP and C# are separate preview cases: whole-app analysis, recording, replay, and a front door are available, but unit-level bridging is not yet implemented.
| Source language | Migration unit | Bridge | Recording runtime |
|---|---|---|---|
| TypeScript / JavaScript | File or folder | napi-rs or wasm-bindgen | Node running the TypeScript sources |
| Python | Module or package | PyO3 with typed conversion and exceptions | The original Python implementation |
| C | Single source file | Same-name C ABI functions and a header | Shared library through ctypes, one process per case |
| Go | Package | Typed cgo calls and a binary wire format | A generated standalone Go driver |
| Ruby | File or module-function folder | A magnus extension | A generated Ruby driver |
| Java | Package of public static methods | JNI wrappers and a binary wire format | A generated reflection driver |
TypeScript structured values receive special handling because JSON cannot represent undefined, NaN, Infinity, negative zero, or lone surrogates faithfully. Generated markers and helpers preserve those values across the binary wire. The analyzer also distinguishes Node-dependent code from portable code, choosing napi-rs when the unit needs Node and wasm-bindgen when it can run in a portable WebAssembly environment.
Whole-app migration without a broken intermediate state
For a full migration, rust-anything analyzes the application shape, entry points, external dependencies, crate fit, and units that must move together. It records the application from the outside. A command-line program is captured through arguments, stdin, environment variables, stdout, stderr, exit codes, and written files. An HTTP service is captured through requests, status codes, relevant headers, and response bodies. A library is proved through the recorded behavior of its public units.
The next step is a Rust front door. In a CLI, the Rust entry point initially forwards every command to the original process. For a server, an axum front door proxies routes that have not moved. For a library, the original package keeps its public API while wired units route through Rust shadows. Every fallback is counted, so progress is measured by the share of external cases still answered by the old implementation rather than by an estimate based on lines of code.
After a unit passes its gate, it is wired into the front door and the full replay must remain at 100 percent while the fallback rate falls. Each wired unit retains a kill switch back to the original implementation. The final app lift is refused until replay reaches 100 percent with zero fallback, the glue is no longer a stub, and every unit passes its gate. The lift runs on a copy first, removes generated binding layers, validates targets and runtime assets, executes formatting, clippy, tests, and a pure-Rust replay, and only then writes the result back. The original project is not modified.
Batch execution and the economics of crossing a bridge
Batch generation is one of the project's strongest differentiators. For each supported language except C, rust-anything can generate a batch class that keeps a collection in Rust and processes it in one call across all available cores. For search workloads, port.rs can also define an index structure that preserves normalized strings, character masks, position tables, or the previous query's matches between calls.
This design addresses a common negative optimization. Calling Rust once for every tiny item may lose to a mature JIT. Moving the loop across the bridge changes the economics: the goal is to keep the data and the repeated work on one side. The bundled TypeScript search example also notes that mapping returned indexes through a plain loop can be much cheaper than using a high-level array transformation, which shows that migration advice extends to the shape of the glue code.
Designed for coding agents, but not controlled by them
rust-anything treats a coding agent as a capable implementer inside a verification loop. The setup command registers a stdio MCP server and a workflow skill with Claude Code, Codex, Cursor, and Gemini CLI. Any other MCP client can add rust-anything mcp manually. The tool surface includes profiling, analysis, bridging, recording, building, diffing, benchmarking, shadow execution, and gating, plus whole-app record, replay, front-door, wire, and lift operations.
The agent can read code, write Rust, and repair mismatches, but it cannot declare a unit complete merely because the crate compiles. rust-anything retains the evidence and denies completion until the recorded behavior and engineering checks agree. Installation is available through crates.io, GitHub release binaries, and npm. Recording and diffing still require the original runtime, such as Node 22.6 or newer, Python 3.9 or newer, Go 1.21 or newer, Ruby 3 or newer, or JDK 17 or newer.
What the gate actually enforces
The gate checks more than compilation. It runs formatting, clippy with warnings treated as errors, Cargo tests, an audit for unimplemented functions and unexplained unsafe code, API coverage, and behavior replay. It also checks whether every intentional error path in the original has a recorded failing case. In functions whose original implementation returns errors, panics from unwrap, expect, or explicit macro calls are not accepted unless the state is demonstrably impossible and documented as such.
Source growth is another signal. If the Rust port exceeds three times the original unit's code size plus a fixed allowance, the gate warns that the implementation is probably hand-rolling work that an existing crate should provide. Shadow mode follows the same conservative philosophy: it executes both sides, reports mismatches, and returns the original result in shadow mode before the new path is enabled.
Evidence has a boundary
Passing the gate means the Rust port matches the recorded cases. It does not prove equivalence for every possible input. Unrecorded production inputs, unobserved branches, platform differences, and side effects can escape the suite. The documentation is unusually direct about this limit and asks teams to add production samples and regression cases before relying on the result.
Regular expressions are a representative risk. Word boundaries, digit classes, case folding, and Unicode behavior differ across JavaScript, Python, Java, and Rust. A port can pass a small generated set and still diverge on real text. Floating-point formatting is another edge: tolerances can forgive small rounding differences, but integer, text, and structural behavior still need exact matches. Timing, memory, concurrency under load, network calls, database effects, signals, and target-platform ABI differences are outside the recorded contract.
The project also resists applying Rust where it creates more risk than value. Code already compiled by numba, Cython, or JAX may gain little. C drivers that depend on hardware registers, compiler layout, inline assembly, or platform-specific types are often better left in C. Electron logic can move while its renderer remains a web UI, and a binary without source is outside the supported workflow.
Who should consider it
The best starting point is an existing source-available system with observable inputs and outputs. For a speed-focused migration, look for parsing, search, normalization, sorting, rules, and other work that can process data in batches. For a whole application, start with a CLI, a service with clear external behavior, or a library with stable public exports. Teams that already maintain useful integration tests can turn those observations into stronger migration cases.
The project is less persuasive when the code depends heavily on runtime reflection, dynamic execution, hardware-specific behavior, or behavior that cannot be captured from observable outputs. That is not a flaw hidden by the marketing; it follows from the evidence model.
rust-anything's broader contribution is a durable migration state machine: plan, bridge, record, implement, diff, benchmark, shadow, gate, wire, and lift. Every step has a rollback path, and every completion claim is tied to repeatable evidence. Teams that want coding agents to assist with large refactors without accepting “it compiles” as proof will find a useful engineering pattern here.
The source and full documentation are available in the GitHub repository. This article is based on the 1.4.0 English and Chinese documentation, the migration workflow files, and the key implementation sources. The repository's benchmark figures were not independently rerun for this article.