💻 computer science

Documentation-Guided Agentic Codebase Migration from C to Rust

RustPrint è un framework agentico guidato dalla documentazione che abilita una migrazione scalabile a livello di repository da C a Rust convertendo il codice sorgente in progetti architetturali per guidare la pianificazione iterativa, la verifica e la riparazione degli agenti, ottenendo un successo di compilazione e una preservazione delle funzionalità superiori rispetto ai traduttori basati su LLM esistenti.

Autori originali: Minh Le-Anh, Anh Nguyen Hoang, Bach Le, Nghi D. Q. Bui

Pubblicato 2026-05-15

📖 5 min di lettura🧠 Approfondimento

CC BY 4.0

Autori originali: Minh Le-Anh, Anh Nguyen Hoang, Bach Le, Nghi D. Q. Bui

Articolo originale sotto licenza CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Questa è una spiegazione generata dall'IA dell'articolo qui sotto. Non è stata scritta né approvata dagli autori. Per precisione tecnica, consulta l'articolo originale. Leggi il disclaimer completo

Immagina di avere una biblioteca enorme e antica scritta in un linguaggio chiamato C. È la base di molti sistemi critici (come sistemi operativi e strumenti di rete), ma è costruita su fondamenta instabili. I "mattoni" (la gestione della memoria) sono allentati e, se non si fa estrema attenzione, l'intera struttura può crollare o essere facilmente violata da intrusi (hacking di sicurezza).

Vuoi ricostruire l'intera biblioteca utilizzando un nuovo linguaggio moderno chiamato Rust. Rust è come una fortezza: dispone di lucchetti di sicurezza automatici che impediscono al palazzo di crollare. Ma ecco il problema: tradurre un'intera biblioteca, mattone per mattone, è incredibilmente difficile. Se traduci solo una stanza alla volta, spesso perdi le planimetrie, dimentichi come le stanze sono collegate o ti ritrovi con un edificio che sembra fatto in Rust ma si comporta come un edificio C rotto.

RustPrint è un nuovo "architetto e squadra di costruzione" (un sistema di agenti AI) progettato per risolvere questo problema. Invece di tradurre semplicemente il codice riga per riga, utilizza una strategia intelligente in tre fasi per garantire che il nuovo edificio sia sicuro, funzionale e fedele al progetto originale.

Ecco come funziona RustPrint, utilizzando semplici analogie:

1. La Fase della "Planimetria" (Documentazione Prima)

La maggior parte degli strumenti di traduzione tenta di tradurre una frase, poi la successiva, poi la successiva. RustPrint si ferma e dice: "Aspetta, leggiamo prima l'intero libro".

Cosa fa: Legge l'intera base di codice C vecchia e scrive un massiccio e dettagliato manuale di istruzioni (documentazione) che descrive come funziona il sistema, come sono collegate le parti e perché è stato costruito in quel modo.
L'Analogia: Immagina di ristrutturare un vecchio castello. Invece di sostituire semplicemente le pietre, prima assumi un esperto per disegnare una mappa perfetta e dettagliata della disposizione del castello, dei passaggi segreti e della logica strutturale. Questa mappa diventa la "planimetria" per la nuova costruzione.
Perché è importante: Questo assicura che l'AI comprenda l'intento del codice, non solo la sintassi. Impedisce all'AI di dimenticare come due stanze diverse devono comunicare tra loro.

2. La Fase della "Costruzione" (Traduzione Agente)

Una volta pronta la planimetria, RustPrint invia un team di lavoratori AI specializzati per costruire la nuova versione in Rust.

Il Pianificatore: Guarda la planimetria e dice: "Dobbiamo costruire la cucina qui, la biblioteca là, e assicurarci che l'impianto idraulico sia collegato". Crea un piano di costruzione passo dopo passo.
Il Costruttore: Costruisce le stanze (moduli di codice) una per una.
L'Ispettore: Dopo che ogni stanza è stata costruita, l'Ispettore esegue un "controllo di sicurezza" (compilazione). Se un muro è storto o un tubo perde (errori di codice), il Costruttore lo ripara immediatamente prima di procedere.
L'Addetto alla Sicurezza: Controlla specificamente le scorciatoie "non sicure". Rust permette codice non sicuro solo se assolutamente necessario, ma questo agente cerca di eliminarle, garantendo che l'edificio finale sia una fortezza.

3. La Fase del "Controllo Qualità" (Il Doppio Controllo)

Qui RustPrint diventa davvero intelligente. Non si fida semplicemente che l'edificio sia finito; lo verifica rispetto all'originale.

Il Controllo "Specchio": Dopo che il nuovo edificio in Rust è stato costruito, l'AI scrive un nuovo manuale di istruzioni per la versione Rust. Confronta poi questo nuovo manuale con il manuale C originale.
- Se il nuovo manuale manca di una sezione (ad esempio, "Il tunnel segreto"), l'AI sa che ha perso una funzionalità e torna indietro per correggerla.
Lo "Stress Test": L'AI prende i test originali (come i test di stress per le mura del castello) e li esegue sul nuovo edificio in Rust. Se una muro si crepa durante il test, l'AI non si limita a ripararlo; capisce perché il muro si è crepato e risolve il difetto di progettazione sottostante.

I Risultati: Ha funzionato?

I ricercatori hanno testato RustPrint su 8 progetti C reali su larga scala (che vanno da piccole librerie a sistemi massicci con oltre 80.000 righe di codice).

La Concorrenza: Altri strumenti (come C2Rust o semplici traduttori AI) hanno provato a farlo ma hanno fallito. O non sono riusciti a finire la costruzione (il codice non si compilava) o hanno costruito una struttura che sembrava Rust ma era piena di buchi.
Il Successo di RustPrint:
- Ha finito il lavoro: RustPrint ha costruito con successo una versione funzionante e compilabile di ogni singolo progetto.
- Ha mantenuto le funzionalità: Ha preservato dal 93% al 97% delle funzionalità originali (a seconda del modello AI utilizzato), mentre altri metodi ne conservavano solo circa il 50%.
- Ha superato i test: Quando hanno eseguito i test originali sul nuovo codice, RustPrint ha superato dal 95% al 98% di essi. Gli altri metodi fallivano significativamente più spesso.
- Era sicuro: Il codice risultante era quasi completamente privo di scorciatoie "non sicure", rendendolo molto più sicuro dei tentativi precedenti.

La Conclusione

RustPrint dimostra che per migrare un sistema software enorme e complesso non puoi essere solo un traduttore; devi essere un architetto. Costringendo l'AI a scrivere prima una "planimetria", confrontando i progetti ed eseguendo test di stress, RustPrint può spostare con successo il codice C legacy nel mondo sicuro e moderno di Rust senza perdere l'anima del sistema originale.

Nota: Il documento si concentra strettamente sulla migrazione tecnica del codice. Non afferma che questo metodo sia pronto per l'uso immediato in dispositivi medici critici per la vita o che risolva tutti i problemi software, ma piuttosto che sia uno strumento altamente efficace per il compito specifico di tradurre grandi basi di codice C in Rust.

Riepilogo Tecnico: RustPrint – Migrazione Agente di Codice Guidata dalla Documentazione da C a Rust

Enunciato del Problema

La migrazione di repository C legacy verso Rust è fondamentale per affrontare le vulnerabilità di sicurezza della memoria intrinseche al modello dei puntatori di C, ma rimane una sfida ingegneristica significativa. Gli strumenti di traduzione esistenti (ad esempio, C2Rust) operano spesso a livello di file o funzione, preservando strutture in stile C e risultando in un uso massiccio di blocchi unsafe, oppure non riescono a catturare l'intento architetturale, il flusso dei dati e la logica di progettazione del sistema originale. Inoltre, gli approcci attuali basati su Large Language Model (LLM) spesso faticano con compiti su scala di repository, fallendo nel produrre output compilabili per grandi codebase (11K–84K righe di codice) a causa della mancanza di una comprensione olistica e del coordinamento tra i moduli. Il problema fondamentale è che la migrazione è essenzialmente un compito di comprensione del codice che richiede un modello mentale delle strutture dati condivise, dei confini dei moduli e delle invarianti tra file, che le strategie di traduzione isolate non possono recuperare.

Metodologia: Il Framework RustPrint

RustPrint è un framework multi-agente progettato per la migrazione da C a Rust a livello di repository. Introduce un paradigma guidato dalla documentazione in cui la documentazione generata automaticamente funge da rappresentazione intermedia (IR) per guidare la pianificazione, la traduzione e il raffinamento. Il framework opera attraverso una pipeline a cinque fasi:

1. Traduzione del Codice Guidata dalla Documentazione

Invece di tradurre il codice unità per unità, RustPrint genera prima una documentazione olistica del codice sorgente C utilizzando un modulo dedicato DocGen.

Processo: Il repository sorgente viene clusterizzato a livello di file, quindi elevato a astrazioni di componente di livello superiore. Il modulo DocGen produce documentazione strutturata ( $S_{doc}$ ) che cattura funzionalità astratte, interazioni tra moduli e logica di progettazione, piuttosto che semplici descrizioni sintattiche.
Agenti:
- Planner: Converte $S_{doc}$ in un piano di implementazione a livello di crate (IMPLEMENTATION_PLAN.md), risolvendo i dettagli architetturali e definendo le responsabilità dei componenti.
- Translator: Implementa ogni crate pianificato, iterando con cargo_check per garantire la compilabilità e detect_unsafe per minimizzare i blocchi unsafe.
- Synthesizer: Esegue l'integrazione a livello di repository, risolvendo le dipendenze incrociate tra crate e generando un README.md unificato.

2. Raffinamento del Codice Guidato dai Requisiti

Per garantire la completezza semantica, RustPrint impiega un meccanismo di raffinamento iterativo che confronta la documentazione del codice Rust generato ( $T_{doc}$ ) con la documentazione sorgente ( $S_{doc}$ ).

Meccanismo: Il sistema approssima la preservazione funzionale tramite equivalenza della documentazione: $CodeEquiv(S, T) \approx DocEquiv(S_{doc}, T_{doc})$ .
Agente: Il RequirementRefiner identifica le lacune in cui $T_{doc}$ non corrisponde a $S_{doc}$ (ad esempio, funzionalità omesse, API non corrispondenti). Modifica il codice tradotto utilizzando str_replace_editor, verifica la compilazione e ripara iterativamente le funzionalità mancanti o non allineate.

3. Revisione del Codice Consapevole dell'Esecuzione

Riconoscendo che il confronto della documentazione non può esporre tutti gli errori di runtime, il framework aggiunge un ciclo di feedback guidato dai test.

Processo: La suite di test sorgente viene tradotta in Rust dal TestTranslator.
Agente: L'ExecutionRevisor analizza i test falliti utilizzando cargo_single_test. Aggiorna solo il codice di produzione tradotto (non i test) per correggere incoerenze comportamentali come casi limite, aggiornamenti di stato o discrepanze di protocollo che sopravvivono all'allineamento statico ma falliscono sotto esecuzione concreta.

Contributi Chiave

Paradigma di Migrazione Guidato dalla Documentazione: Il documento propone l'uso della documentazione del codice generata automaticamente come rappresentazione intermedia per la traduzione a livello di repository. Questo approccio codifica la comprensione dell'intero codice prima della traduzione, consentendo la generazione di Rust idiomatico che preserva l'intento architetturale invece di replicare meramente la struttura sintattica.
Raffinamento Iterativo Guidato dalla Documentazione: Un meccanismo che valuta e migliora il codice Rust generato confrontando la sua documentazione con quella sorgente, identificando sistematicamente le lacune di copertura e promuovendo l'allineamento strutturale.
Revisione Consapevole dell'Esecuzione: L'integrazione del feedback guidato dai test permette al sistema di correggere iterativamente le incoerenze comportamentali attraverso l'esecuzione dinamica dei test, raggiungendo la correttezza funzionale oltre quanto garantito dalla traduzione statica.
Valutazione su Grande Scala: Il framework è stato valutato su otto repository C reali che variano da 11K a 84K righe di codice, affrontando la limitazione dei lavori precedenti focalizzati su piccoli benchmark.

Risultati Sperimentali

La valutazione è stata condotta su otto repository utilizzando due backbones di modello: un modello open-weight (Kimi-K2-Instruct) e un modello closed-weight (GPT-5.4). I baseline includevano strumenti tradizionali (C2Rust) e agenti basati su LLM (Self-Repair, EvoC2Rust e un baseline agente Claude Code).

Compilabilità del Progetto: RustPrint ha compilato con successo ogni repository target sotto entrambi i backbones di modello. Al contrario, i traduttori LLM baseline (Self-Repair, EvoC2Rust) non sono riusciti a produrre repository compilabili end-to-end a questa scala. C2Rust ha compilato ma ha mantenuto un uso pesante di unsafe.
Preservazione delle Funzionalità: Misurata tramite il punteggio CodeWikiBench, RustPrint ha superato significativamente il baseline Claude Code.
- Con Kimi-K2-Instruct: RustPrint ha raggiunto il 93,26% contro il 52,52% di Claude Code.
- Con GPT-5.4: RustPrint ha raggiunto il 97,76% contro il 48,87% di Claude Code.
Correttezza Funzionale: Utilizzando un protocollo di cross-valutazione (testando l'output di RustPrint con i test di Claude Code e viceversa), RustPrint ha dimostrato una robustezza superiore.
- Kimi-K2-Instruct: 95,17% di Tasso di Successo dei Test (TPR) contro il 79,85% di Claude Code.
- GPT-5.4: 98,70% di TPR contro il 79,85% di Claude Code.
Sicurezza: RustPrint ha raggiunto alti tassi di sicurezza, minimizzando i blocchi unsafe. Con GPT-5.4, ha raggiunto tassi di sicurezza del 99,41% a livello di API e del 98,47% a livello di file, superando altri metodi.

Significato e Affermazioni

Il documento afferma che il coordinamento guidato dalla documentazione è una direzione vitale ed efficace per la migrazione scalabile di codebase. I risultati suggeriscono che trattare la migrazione come un problema di coordinamento tra file, interfacce e passaggi di riparazione – piuttosto che come un compito di generazione di codice grezzo – è essenziale per il successo su scala di repository.

Gli autori sottolineano che:

Pianificazione e raffinamento contano più della traduzione one-shot: Il ciclo iterativo di generazione della documentazione, confronto con la sorgente e raffinamento basato sul feedback di esecuzione è critico per gestire dipendenze complesse tra moduli.
La documentazione funge da guida operativa: Non è semplicemente contesto di sfondo, ma una bozza funzionale che guida il recupero dei requisiti mancanti e l'allineamento strutturale.
La correttezza comportamentale è raggiungibile: I risultati dei test incrociati indicano che i guadagni non sono solo documentali; i repository tradotti preservano il comportamento di runtime effettivo.

Il documento conclude che, sebbene lo studio attuale rappresenti un forte primo risultato su repository realistici, l'approccio lascia chiari percorsi per miglioramenti futuri, come la gestione di repository multilingua, dipendenze esterne più profonde e sistemi di build meno standardizzati. Gli autori posizionano RustPrint come un metodo pratico per scalare la traduzione basata su LLM da file isolati a compiti ingegneristici completi a livello di repository.