💻 computer science

Documentation-Guided Agentic Codebase Migration from C to Rust

RustPrint is a documentation-guided agentic framework that enables scalable, repository-level migration from C to Rust by converting source code into architectural blueprints to guide iterative agent planning, verification, and repair, achieving superior compilation success and feature preservation compared to existing LLM-based translators.

Original authors: Minh Le-Anh, Anh Nguyen Hoang, Bach Le, Nghi D. Q. Bui

Published 2026-05-15

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Minh Le-Anh, Anh Nguyen Hoang, Bach Le, Nghi D. Q. Bui

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you have a massive, old library written in a language called C. It's the foundation of many critical systems (like operating systems and network tools), but it's built on shaky ground. The "bricks" (memory management) are loose, and if you aren't extremely careful, the whole structure can collapse or be easily broken into by intruders (security hacks).

You want to rebuild this entire library using a new, modern language called Rust. Rust is like a fortress: it has automatic safety locks that prevent the building from collapsing. But here's the problem: translating a whole library, brick by brick, is incredibly hard. If you just translate one room at a time, you often lose the blueprints, forget how the rooms connect, or end up with a building that looks like Rust but acts like a broken C building.

RustPrint is a new "architect and construction crew" (an AI agent system) designed to solve this. Instead of just translating code line-by-line, it uses a clever three-step strategy to ensure the new building is safe, functional, and true to the original design.

Here is how RustPrint works, using simple analogies:

1. The "Blueprint" Phase (Documentation-First)

Most translation tools try to translate a sentence, then the next sentence, then the next. RustPrint stops and says, "Wait, let's read the whole book first."

What it does: It reads the entire old C codebase and writes a massive, detailed instruction manual (documentation) describing how the system works, how the parts connect, and why it was built that way.
The Analogy: Imagine you are renovating an old castle. Instead of just swapping out the stones, you first hire an expert to draw a perfect, detailed map of the castle's layout, secret passages, and structural logic. This map becomes the "blueprint" for the new build.
Why it matters: This ensures the AI understands the intent of the code, not just the syntax. It prevents the AI from forgetting how two different rooms need to talk to each other.

2. The "Construction" Phase (Agentic Translation)

Once the blueprint is ready, RustPrint sends a team of specialized AI workers to build the new Rust version.

The Planner: Looks at the blueprint and says, "We need to build the kitchen here, the library there, and make sure the plumbing connects." It creates a step-by-step construction plan.
The Builder: Builds the rooms (code modules) one by one.
The Inspector: After every room is built, the Inspector runs a "safety check" (compilation). If a wall is crooked or a pipe leaks (code errors), the Builder fixes it immediately before moving on.
The Safety Officer: Specifically checks for "unsafe" shortcuts. Rust allows unsafe code only if absolutely necessary, but this officer tries to eliminate them, ensuring the final building is a fortress.

3. The "Quality Control" Phase (The Double-Check)

This is where RustPrint gets really smart. It doesn't just trust that the building is done; it verifies it against the original.

The "Mirror" Check: After the new Rust building is built, the AI writes a new instruction manual for the Rust version. It then compares this new manual against the original C manual.
- If the new manual is missing a section (e.g., "The secret tunnel"), the AI knows it missed a feature and goes back to fix it.
The "Stress Test": The AI takes the original tests (like stress tests for the castle walls) and runs them on the new Rust building. If a wall cracks during the test, the AI doesn't just patch it; it figures out why the wall cracked and fixes the underlying design flaw.

The Results: Did it work?

The researchers tested RustPrint on 8 real-world, large-scale C projects (ranging from small libraries to massive systems with over 80,000 lines of code).

The Competition: Other tools (like C2Rust or simple AI translators) tried to do this but failed. They either couldn't finish the build (the code wouldn't compile) or they built a structure that looked like Rust but was full of holes.
RustPrint's Success:
- It finished the job: RustPrint successfully built a working, compilable version of every single project.
- It kept the features: It preserved 93% to 97% of the original features (depending on the AI model used), whereas other methods only kept about 50%.
- It passed the tests: When they ran the original tests on the new code, RustPrint passed 95% to 98% of them. Other methods failed significantly more often.
- It was safe: The resulting code was almost entirely free of "unsafe" shortcuts, making it much more secure than previous attempts.

The Bottom Line

RustPrint proves that to migrate a massive, complex software system, you can't just be a translator; you have to be an architect. By forcing the AI to write a "blueprint" first, compare the plans, and run stress tests, RustPrint can successfully move legacy C code into the safe, modern world of Rust without losing the soul of the original system.

Note: The paper focuses strictly on the technical migration of code. It does not claim this method is ready for immediate use in life-critical medical devices or that it solves all software problems, but rather that it is a highly effective tool for the specific task of translating large C codebases to Rust.

Technical Summary: RustPrint – Documentation-Guided Agentic Codebase Migration from C to Rust

Problem Statement

The migration of legacy C repositories to Rust is critical for addressing memory safety vulnerabilities inherent in C's pointer model, yet it remains a significant engineering challenge. Existing translation tools (e.g., C2Rust) often operate at the file or function level, preserving C-style structures and resulting in heavy usage of unsafe blocks, or they fail to capture the architectural intent, data flow, and design rationale of the original system. Furthermore, current Large Language Model (LLM)-based approaches often struggle with repository-scale tasks, failing to produce compilable outputs for large codebases (11K–84K Lines of Code) due to a lack of holistic understanding and coordination across modules. The core problem is that migration is fundamentally a codebase-understanding task requiring a mental model of shared data structures, module boundaries, and cross-file invariants, which isolated translation strategies cannot recover.

Methodology: The RustPrint Framework

RustPrint is a multi-agent framework designed for repository-level C-to-Rust migration. It introduces a documentation-driven paradigm where automatically generated documentation serves as an intermediate representation (IR) to guide planning, translation, and refinement. The framework operates through a five-stage pipeline:

1. Documentation-Guided Code Translation

Instead of translating code unit-by-unit, RustPrint first generates holistic documentation of the source C codebase using a dedicated DocGen module.

Process: The source repository is clustered at the file level, then lifted into higher-level component abstractions. The DocGen module produces structured documentation ( $S_{doc}$ ) that captures abstract features, module interactions, and design rationale, rather than just syntactic descriptions.
Agents:
- Planner: Converts $S_{doc}$ into a crate-level implementation plan (IMPLEMENTATION_PLAN.md), resolving architectural details and defining component responsibilities.
- Translator: Implements each planned crate, iterating with cargo_check to ensure compilability and detect_unsafe to minimize unsafe blocks.
- Synthesizer: Performs repository-level integration, resolving cross-crate dependencies and generating a unified README.md.

2. Requirement-Driven Code Refinement

To ensure semantic completeness, RustPrint employs an iterative refinement mechanism that compares the documentation of the generated Rust codebase ( $T_{doc}$ ) against the source documentation ( $S_{doc}$ ).

Mechanism: The system approximates functional preservation via documentation equivalence: $CodeEquiv(S, T) \approx DocEquiv(S_{doc}, T_{doc})$ .
Agent: The RequirementRefiner identifies gaps where $T_{doc}$ fails to match $S_{doc}$ (e.g., omitted features, mismatched APIs). It edits the translated code using str_replace_editor, checks compilation, and iteratively repairs missing or misaligned functionality.

3. Execution-Aware Code Revision

Recognizing that documentation comparison cannot expose all runtime errors, the framework adds a test-driven feedback loop.

Process: The source test suite is translated to Rust by the TestTranslator.
Agent: The ExecutionRevisor analyzes failing tests using cargo_single_test. It updates only the translated production code (not the tests) to fix behavioral inconsistencies such as edge cases, state updates, or protocol mismatches that survive static alignment but fail under concrete execution.

Key Contributions

Documentation-Driven Migration Paradigm: The paper proposes using automatically generated codebase documentation as an intermediate representation for repository-level translation. This approach encodes whole-codebase understanding before translation, enabling the generation of idiomatic Rust that preserves architectural intent rather than merely replicating syntactic structure.
Documentation-Guided Iterative Refinement: A mechanism that assesses and improves generated Rust code by comparing its documentation against the source, systematically identifying coverage gaps and promoting structural alignment.
Execution-Aware Revision: The integration of test-driven feedback allows the system to iteratively correct behavioral inconsistencies through dynamic test execution, achieving functional correctness beyond what static translation guarantees.
Large-Scale Evaluation: The framework is evaluated on eight real-world C repositories ranging from 11K to 84K LoC, addressing the limitation of prior work that focused on small benchmarks.

Experimental Results

The evaluation was conducted on eight repositories using two model backbones: an open-weight model (Kimi-K2-Instruct) and a closed-weight model (GPT-5.4). Baselines included traditional tools (C2Rust) and LLM-based agents (Self-Repair, EvoC2Rust, and an agentic Claude Code baseline).

Project Compilability: RustPrint successfully compiled every target repository under both model backbones. In contrast, baseline LLM translators (Self-Repair, EvoC2Rust) failed to produce end-to-end compilable repositories at this scale. C2Rust compiled but retained heavy unsafe usage.
Feature Preservation: Measured via the CodeWikiBench score, RustPrint significantly outperformed the Claude Code baseline.
- With Kimi-K2-Instruct: RustPrint achieved 93.26% vs. 52.52% for Claude Code.
- With GPT-5.4: RustPrint achieved 97.76% vs. 48.87% for Claude Code.
Functional Correctness: Using a cross-evaluation protocol (testing RustPrint's output with Claude Code's tests and vice versa), RustPrint demonstrated superior robustness.
- Kimi-K2-Instruct: 95.17% Test Pass Rate (TPR) vs. 79.85% for Claude Code.
- GPT-5.4: 98.70% TPR vs. 79.85% for Claude Code.
Safety: RustPrint achieved high safety rates, minimizing unsafe blocks. With GPT-5.4, it reached 99.41% API-level and 98.47% file-level safe rates, outperforming other methods.

Significance and Claims

The paper claims that documentation-guided coordination is a viable and effective direction for scalable codebase migration. The results suggest that treating migration as a coordination problem across files, interfaces, and repair steps—rather than a raw code-generation task—is essential for repository-scale success.

The authors emphasize that:

Planning and refinement matter more than one-shot translation: The iterative loop of generating documentation, comparing it against the source, and refining based on execution feedback is critical for handling complex cross-module dependencies.
Documentation acts as an operational guide: It is not merely background context but a functional blueprint that drives the recovery of missing requirements and structural alignment.
Behavioral correctness is achievable: The cross-suite test results indicate that the gains are not just documentary; the translated repositories preserve actual runtime behavior.

The paper concludes that while the current study represents a strong first result on realistic repositories, the approach leaves clear paths for future improvement, such as handling mixed-language repositories, deeper external dependencies, and less standardized build systems. The authors position RustPrint as a practical method to scale LLM-based translation from isolated files to full repository-level engineering tasks.