port-to-rust
Run a port into Rust without losing behaviour — define the parity contract, sequence the phases, migrate incrementally behind a stable boundary, and prove parity differentially. Use when moving, porting, rewriting, or migrating an existing codebase into Rust from any language, when deciding how to sequence or scope a rewrite, when a port needs to prove it matches its source, or when a partially-ported system needs both implementations running side by side.
rewrite-rs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rewrite-rs/skills --skill port-to-rust技能说明
name: port-to-rust description: Run a port into Rust without losing behaviour — define the parity contract, sequence the phases, migrate incrementally behind a stable boundary, and prove parity differentially. Use when moving, porting, rewriting, or migrating an existing codebase into Rust from any language, when deciding how to sequence or scope a rewrite, when a port needs to prove it matches its source, or when a partially-ported system needs both implementations running side by side.
Port to Rust
A port is a behaviour-preserving move, and nothing else
The one rule this skill exists to enforce: during a port, behaviour changes and code improvements are separate commits, separate reviews, and preferably separate weeks. A port that also fixes bugs cannot be validated — every difference is ambiguous between the fix and the regression, and the differential harness reports both identically. Improvements are written down as a follow-up list and shipped after parity is proven.
Start from the parity contract, not from the code
Before any Rust is written, the contract answers four questions: what the
unit of parity is (a CLI invocation, a library function, an HTTP response, a
file artifact); which differences are acceptable (log wording, timing, map
iteration order, float formatting); which are not (any observable output a
caller can branch on); and how parity is measured — the full form in
PARITY-CONTRACT.md. A port without a written contract does not have a
definition of done, so it finishes when someone gets tired.
Five phases, in order
| Phase | Ends when |
|---|---|
| 1. Inventory and seam | The boundary the Rust will live behind is named, and the call sites crossing it are counted |
| 2. Characterize | The existing behaviour is captured as executable tests — against the source implementation, not the intended one |
| 3. Port leaf-first | The lowest-dependency module is in Rust, called through the seam, with both implementations still present |
| 4. Run both | Every input reaching the seam goes through both implementations and the outputs are compared |
| 5. Cut over and delete | Traffic goes to Rust only, and the source implementation is deleted rather than left as a dead fallback |
Phase 2 characterizes the behaviour that exists, bugs included — a test that
asserts the intended behaviour is a bug report disguised as a test. Phase 5
is not optional: a source implementation left in place stops being maintained
and starts being a lie about what runs; the depth on each phase is in
PHASES.md.
Decide the end state before the seam
Three end states; the choice governs everything downstream — the seam, the contract, the verification, whether bindings are deliverable or scaffold:
| End state | What ships | Bindings |
|---|---|---|
| A. Replacement | A standalone Rust binary or crate; the source implementation is deleted | None, ever. The seam is a process, CLI, or network boundary |
| B. Rust core with a language binding as the product | A Rust engine plus a binding layer that stays — the package the existing consumers import is the deliverable | Permanent. The binding surface is public API: it gets semver, error-type mapping, packaging per platform, and its own docs |
| C. Bindings as scaffold | A standalone Rust binary or crate, reached through a binding layer that is deleted at cut-over | Temporary. Built to be thrown away, and phase 5 is not done until it is gone |
B and C are not the same work, and conflating them is the most expensive mistake here. Scaffold bindings may be crude because they die; product bindings are a public surface that outlives the port. Ask which one is wanted — a user porting a CLI to Rust usually wants A, and handing them a native extension module answers a question nobody asked. The answer goes in the parity contract, because it changes what the unit of parity is: for A the unit is an invocation or a request; for B it is the binding signature the existing callers already call.
Pick the incremental strategy from the seam, not from taste
| Strategy | Reach for it when |
|---|---|
| In-place FFI — Rust compiled into the existing build and called across a language boundary | The source language has a cheap, stable FFI story and the seam is a function call |
| Strangler at a process boundary — the Rust binary takes traffic for one route, endpoint, or subcommand at a time | The seam is already a process, socket, or CLI boundary; the languages do not interoperate cheaply |
| Whole-unit replacement | The unit is small enough to port and validate in one sitting — a single CLI tool, one library with a narrow surface |
The FFI mechanics — which crate, which build integration, which header generator — sit in the per-language skills.
Parity is proven, not asserted
The evidence is both implementations running over the same inputs and
agreeing. Building that harness is /rust-testing; this skill decides what
it has to cover — every input class the contract names, including the error
paths, which are the ones a port silently narrows — and the harness runs in
CI from phase 3 onward, not once at the end, because a difference found six
modules later cannot be attributed.
What is deliberately not ported
Dead code, workarounds for limitations the source language had and Rust does not, and abstraction layers that existed to work around the source type system — each a judgment call written down in the contract, not made silently mid-file. The inverse error is worse and more common: porting the abstraction rather than the behaviour, so a five-layer class hierarchy becomes five Rust traits nobody needs.
Where the target-side judgment goes
This skill never decides what the Rust should look like. Expression shape is
/idiomatic-rust; a clone added to satisfy the borrow checker mid-port is
/ownership-not-clone; what a fallible path returns is /rust-errors;
whether a state should be constructible at all is /type-driven-design;