Riepilogo Tecnico: Prefactory – Scoperta Automatica e Applicazione di Refactoring per l'Adozione di Librerie

Definizione del Problema

Il refactoring per l'adozione di librerie consiste nel sostituire implementazioni di codice scritte a mano con chiamate a API di librerie esistenti. Questa pratica riduce la dimensione del codice, migliora la qualità idiomatica e sfrutta implementazioni ben testate. Tuttavia, automatizzare questo processo è difficile perché:

1. Mancanza di Segnali Espliciti: Il codice originale scritto a mano spesso non menziona la libreria target o la specifica API, rendendo difficile per gli strumenti che si basano su istruzioni di importazione o riferimenti diretti trovare le opportunità.
2. Variabilità Sintattica: Gli sviluppatori implementano la stessa funzionalità in modi diversi (nomi di variabili differenti, flussi di controllo o funzioni helper), il che significa che i pattern sintattici fissi o le regole dei linter spesso non riescono a generalizzare.
3. Limitazioni degli Approcci Esistenti:
   • Strumenti Statici: Linter e modernizzatori (es. Ruff, Pylint) sono efficaci solo per pattern precisi e specificati manualmente.
   • Agenti LLM: Sebbene i Large Language Models (LLM) possano generalizzare a pattern vari, l'uso di essi per scansionare interi codebase tramite prompt ripetuti è costoso, difficile da rendere riproducibile e difficile da controllare sistematicamente su larga scala.

Il collo di bottiglia principale è la rilevazione (detection): trovare regioni di codice rilevanti senza menzioni esplicite della libreria e generalizzare oltre i template fissi, seguito dalla generazione di una sostituzione che preservi il comportamento.

Metodologia: La Pipeline di Prefactory

Prefactory è una pipeline automatizzata in quattro fasi progettata per convertire la conoscenza semantica degli LLM in meccanismi di ricerca deterministici e riutilizzabili. Opera su un progetto target e un nome di libreria target.

Fase 1: Generazione dei Detector

Invece di istruire un LLM per scansionare direttamente il codice, Prefactory utilizza un LLM per sintetizzare detector eseguibili.

• Input: Metadati della libreria target (da PyPI, documentazione ed esempi estratti di passati refactoring) e vocabolario del progetto (nomi frequenti dal progetto target).
• Output: Due famiglie di detector:
  1. Detector Lessicali: Espressioni regolari che corrispondono a termini di dominio, nomi relativi alle API e pattern testuali associati a implementazioni scritte a mano.
  2. Detector Strutturali: Matcher AST (Abstract Syntax Tree) che identificano forme algoritmiche (es. loop su valori, computazione di indici aritmetici, accumulo in strutture dati) indipendentemente dai nomi specifici delle variabili.
• Validazione: I detector generati sono filtrati per garantire che compilino, non vadano in crash e non producano match eccessivamente ampi (es. che corrispondano a >20% dei file).

Fase 2: Scansione del Progetto

Questa fase è deterministica e priva di LLM.

• Prefactory filtra i file non sorgente (es. codice vendored, test, documentazione).
• I detector lessicali e strutturali validati vengono eseguiti contro i file sorgente rimanenti.
• I match vengono registrati, identificando i file e le funzioni candidati, insieme al particolare match del detector che ha attivato il flag.

Fase 3: Classificazione e Filtraggio dei Candidati

Per gestire i costi degli LLM, Prefactory classifica i candidati e seleziona un piccolo sottoinsieme per la riscrittura.

• Metrica di Classificazione: Per ogni candidato $c$, viene calcolato un tuple $(D(c), B(c), -S(c))$:
  • $D(c)$: Forza del match del detector (somma pesata dei match, dando priorità ai match strutturali).
  • $B(c)$: Densità di pattern di implementazione Python base (loop, aritmetica, rami) che indicano logica scritta a mano.
  • $S(c)$: Dimensione del candidato (si preferiscono quelli più piccoli).
• Selezione: Vengono selezionati i primi 5 file e, all'interno di essi, le prime 10 funzioni vengono scelte per la fase successiva.

Fase 4: Generazione e Validazione del Refactoring

• Generazione: Un LLM viene istruito con la funzione candidata, il contesto circostante, gli indizi sulle API della libreria target e i match specifici del detector. Tenta di riscrivere la funzione utilizzando la libreria target.
• Filtraggio della Rilevanza: Controlli basati su AST assicurano che l'edit chiami effettivamente la libreria target e non sia un cambiamento puramente cosmetico.
• Validazione:
  1. Test Differenziali: Un LLM genera uno script di test stand-alone che confronta le funzioni originale e refactored su input generati (usando l'originale come oracle). Se il test fallisce, l'LLM viene interrogato per riparare l'edit (fino a 3 tentativi).
  2. Test di Progetto: Se i test differenziali passano, il codice refactored viene eseguito contro la suite di test esistente del progetto per garantire l'assenza di regressioni.

Contributi Chiave

1. PrefactoryBench: Un benchmark di 100 refactoring di adozione di librerie reali provenienti da 61 progetti open-source Python e 18 librerie. Include ambienti di esecuzione di riferimento, test di progetto e test "held-out" per valutare sia la rilevazione che la trasformazione.
2. Sistema Prefactory: Un approccio automatizzato che sintetizza detector riutilizzabili ed eseguibili (lessicali e strutturali) dalla conoscenza degli LLM, consentendo una scansione efficiente e deterministica senza chiamate ripetute all'LLM durante la fase di ricerca.
3. Evidenza Empirica: Un confronto controllato che dimostra come la sintesi dei detector superi il prompting diretto degli LLM, la ricerca agentica e gli strumenti basati su regole in termini di accuratezza della rilevazione e costo-efficienza.

Risultati

Valutato su PrefactoryBench, Prefactory ha ottenuto i seguenti risultati:

• Rilevazione: Ha rilevato 75 istanze a livello di file e 5_6 a livello di funzione.
• Refactoring: Ha prodotto 40 refactoring validati (che superano sia i test differenziali che quelli di progetto) partendo dai 56 funzioni rilevate.
• Confronto: Ha superato il baseline più forte, Codex CLI (che ha rilevato 35 file e 32 funzioni e prodotto 22 refactoring validati), così come linter, il vanilla LLM prompting e Semgrep+LLM.
• Efficienza:
  • Tempo di Scansione: Media di 1,3 secondi per progetto (senza LLM).
  • Costo: Il costo end-to-end è inferiore a $0,05 per istanza, circa un terzo del costo del baseline Codex CLI.
  • Riutilizzabilità: I detector vengono generati una sola volta per coppia progetto-libreria e riutilizzati per la scansione, rendendo le scansioni ripetute economiche.
• Applicazione nel Mondo Reale: In uno studio sulle versioni correnti di cinque progetti benchmark, Prefactory ha fatto emergere opportunità azionabili, con due pull request accettate dai manutentori.

Significato e Affermazioni

L'articolo afferma che la sintesi dei detector è un workflow pratico e scalabile per il refactoring di adozione delle librerie. Trasformando la conoscenza semantica dell'LLM in meccanismi di ricerca deterministici ed eseguibili, Prefactory evita l'alto costo e i problemi di riproducibilità della ricerca agentica diretta.

Gli autori notano che l'approccio è più efficace quando le opportunità di libreria espongono sia un vocabolario che strutture di implementazione riconoscibili. Rimangono delle limitazioni per le librerie grandi e eterogenee (es. numpy, pandas) dove le opportunità spaziano tra molte famiglie di API, e per il codice che coinvolge I/O complessi o comportamenti distribuiti dove la validazione differenziale è difficile. Il lavoro dimostra che catturare la conoscenza dell'LLM in detector eseguibili e riutilizzabili è più efficace e meno costoso rispetto all'applicazione del ragionamento dell'LLM attraverso query ampie e ripetute.