Req2Rust

Req2Rust is a requirements-guided agent harness for project-level C++ to Rust migration. This repository contains the Req2Rust project source code, paper evaluation scripts, compact paper results, and final translated Rust crate sources used for the reported experiments.

The agent workflow treats an existing Rust crate as an executable refinement state. It runs real build checks, passes compiler and validation reports to a local repair agent, and records the repair trajectory and final check result.

Repository Layout

• framework/agentic_codegen/: JSON-action repair agent runner, repair prompts, semantic-audit prompts, and unsafe-refactor audit utilities.
• framework/io/: OpenAI-compatible JSON client used by the repair agent.
• scripts/run_post_repair_agent.py: lightweight entry point for running the repair agent on an existing Rust crate.
• scripts/run_post_repair_smoke.py: copies the bundled initial Rust smoke crate into output/ and runs the repair-agent entry point.
• scripts/paper_experiments/: evaluation and probe scripts used by the paper experiments.
• scripts/check_paper_numbers.py: checks that the public result tables match the paper numbers.
• examples/initial_crates/: a minimal initial Rust crate snapshot for exercising the smoke workflow.
• examples/semantic_reports/: the corresponding minimal semantic report used by the smoke workflow.
• results/paper_results.json: compact table-level result data from the paper.
• results/rq1/, results/rq2/, results/rq3_ablation/: compact CSV metrics.
• results/translated_crates/: final translated Rust crate sources for the reported RQ1 and RQ2 subjects.
• results/translated_crates/manifest.json: minimal crate snapshot manifest.
• tests/: minimal regression tests for the public result package.

Setup

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r requirements.txt

For agent execution, configure an OpenAI-compatible DeepSeek endpoint:

export DEEPSEEK_API_KEY=...
export DEEPSEEK_BASE_URL=https://api.deepseek.com
export DEEPSEEK_MODEL=deepseek-v4-pro

Run the Repair Agent

Run the repair agent on an existing Rust crate:

python3 scripts/run_post_repair_agent.py \
  --crate-dir results/translated_crates/rq1/ours/uriparser \
  --output-dir output/post_repair_uriparser \
  --profile generic \
  --force

Optional inputs:

• --semantic-report path/to/report.md: include a semantic-audit report as a repair obligation.
• --unsafe-report path/to/report.md: include an unsafe-refactor report as a repair obligation.
• --profile ohos: use OpenHarmony-oriented repair constraints.

The script writes agent_context.json, cargo logs, LLM call logs, the repair trajectory, workspace diff, and summary.json under the output directory.

Smoke Test the Repair Agent

The repository includes one small initial Rust crate snapshot and a semantic report for a duplicate-alias repair. The smoke script copies the crate into output/ before invoking the repair agent, so the tracked example remains unchanged:

python3 scripts/run_post_repair_smoke.py --reset

This command requires the same DeepSeek environment variables as the main repair-agent entry point.

Paper Results

The paper reports three research questions.

RQ1 evaluates seven general C++ projects. Req2Rust passes 193/210 selected tests, or 91.9%, while ClaudeCode passes 146/210, or 69.5%.

RQ2 evaluates five OpenHarmony modules. Req2Rust reaches a module-average test pass rate of 87.9%, while ClaudeCode reaches 45.4%.

RQ3 evaluates ablations on the seven general C++ projects:

Variant	Build	Tests	Unsafe
Full Req2Rust	7/7	91.90%	1.7757%
No semantic validator	7/7	28.10%	1.3227%
No unsafe reduction	7/7	91.90%	4.9950%
Initial Rust only	0/7	0.00%	3.3392%

Check the public numbers:

python3 scripts/check_paper_numbers.py

Tests

python3 -m pytest -q

This test suite validates the compact public result package against the paper values.

Evaluation Scripts

The probe scripts in scripts/paper_experiments/ are included for reproducibility of the evaluation workflow. Full reruns require the original benchmark source trees, OpenHarmony checkout, Rust toolchain, and translated crate paths. The compact CSV and JSON files under results/ are the canonical public result package for the paper tables.

Notes

The repository excludes local build caches, probe crate build directories, API keys, and machine-specific environment files.