💻 computer science

The ARDoCo Tool Landscape: REST API, TraceView, and TraceViz for Architecture Traceability

Questo articolo presenta l'ARDoCo Tool Landscape, una suite pubblicamente disponibile che comprende un'API REST, un frontend basato su browser (TraceView) e un'estensione per VS Code (TraceViz) che rende il recupero dei collegamenti di tracciabilità all'avanguardia accessibile a sviluppatori e architetti, dimostrando al contempo un migliore apprendimento attraverso la visualizzazione integrata nell'IDE.

Autori originali: Jan Keim, Dominik Fuchß, Sophie Corallo, Tobias Hey, Julian Winter, Kevin Feichtinger

Pubblicato 2026-06-29

📖 4 min di lettura☕ Lettura da pausa caffè

CC BY 4.0

Autori originali: Jan Keim, Dominik Fuchß, Sophie Corallo, Tobias Hey, Julian Winter, Kevin Feichtinger

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 essere l'architetto di una città massiccia e complessa. Hai tre diversi set di progetti per questa città:

Il Libro delle Storie (SAD): Una descrizione scritta di come la città dovrebbe funzionare, scritta in un inglese semplice.
I Diagrammi (SAM): Disegni formali e modelli che mostrano come gli edifici e le strade si collegano tra loro.
La Costruzione (Codice): I mattoni, la malta e i cablaggi reali che compongono la vera città.

Il problema è che queste tre cose spesso divergono. Il Libro delle Storie potrebbe dire "costruisci un ponte", ma i Diagrammi lo hanno dimenticato, e la squadra di Costruzione ha costruito un tunnel al suo posto. Mantenere tutto in sincronia è un incubo per gli esseri umani perché c'è troppa informazione da tracciare manualmente.

Questo documento introduce un "kit di strumenti magici" chiamato ARDoCo che trova automaticamente le connessioni tra questi tre progetti e individua dove discordano. Per rendere questo kit facile da usare per tutti, il team ha costruito tre diverse "porte" nel sistema:

1. La Sala Macchine: L'API REST

Pensala come alla centrale elettrica principale. È il macchinario pesante che compie il lavoro effettivo di confronto tra il Libro delle Storie, i Diagrammi e la Costruzione.

A chi è rivolto: Altri strumenti software o programmatori che vogliono collegare questo motore ai propri sistemi.
Come funziona: Invii i tuoi progetti a questo motore tramite internet. Esso esegue il confronto, salva i risultati (così non deve rifare il lavoro se lo richiedi di nuovo) e invia la risposta. È come ordinare una pizza: invii l'ordine, la cucina cucina e consegna il risultato.

2. La Torre di Controllo: TraceView

Questa è una dashboard basata sul web che chiunque può aprire in un browser senza installare nulla.

A chi è rivolta: Architetti e manager che hanno bisogno di vedere il "quadro generale".
Come funziona: Immagina uno schermo diviso in tre finestre. A sinistra c'è il tuo Libro delle Storie, al centro i tuoi Diagrammi e a destra la tua Costruzione. Quando clicchi su una frase nel Libro delle Storie, lo strumento evidenzia istantaneamente la parte corrispondente nei Diagrammi e nella Costruzione sugli altri schermi. Funziona anche come un riflettore per gli errori, lampeggiando in rosso quando il Libro delle Storie menziona un edificio che non esiste nei Diagrammi.

3. Il Display a Testa Alta (HUD): TraceViz

Questo è un add-on speciale per lo spazio di lavoro degli sviluppatori software (specificamente per un programma chiamato VS Code).

A chi è rivolto: Ai veri costruttori (developer) che scrivono il codice.
Come funziona: Invece di costringerti a cambiare finestra, questo strumento dipinge piccoli puntini colorati proprio accanto alle righe di codice che stai scrivendo. Se ci passi sopra con il mouse, ti dice: "Ehi, questa riga di codice si collega a questa frase nel Libro delle Storie". È come un GPS per il codice, che ti permette di saltare istantaneamente da un requisito scritto all'esatto pezzo di codice che lo soddisfa, senza mai lasciare la tua scrivania.

Ha funzionato?

Il team ha testato questi strumenti su progetti software reali.

Il Motore: Il collegamento automatico è molto bravo a trovare le connessioni, riuscendoci spesso più dell'80% delle volte, il che è un enorme miglioramento rispetto al non fare nulla.
Il Display a Testa Alta: Hanno chiesto a un piccolo gruppo di sviluppatori di usare lo strumento. Il risultato? Tutti sono concordi sul fatto che li abbia aiutati a comprendere meglio il codice. Prima di usare lo strumento, dovevano cercare manualmente tra le cartelle per trovare le connessioni. Con i puntini colorati, potevano saltare direttamente alla risposta. Uno sviluppatore ha persino detto che sarebbe fantastico per l'addestramento dei nuovi assunti.

Il succo del discorso

Il team di ARDoCo ha preso una ricerca informatica complessa e difficile da usare e l'ha trasformata in un kit di strumenti amichevole. Che tu voglia far girare il motore da solo, guardare una dashboard nel tuo browser o vedere le connessioni mentre programmi, c'è uno strumento per te per mantenere i progetti della tua città software in perfetta sincronia.

Sintesi Tecnica: Il Panorama degli Strumenti ARDoCo

Contesto del Problema
Lo sviluppo del software genera artefatti interrelati attraverso molteplici livelli di astrazione: documentazione di architettura software (SAD) in linguaggio naturale, modelli di architettura software (SAM) formali e codice sorgente. Mantenere la coerenza e la tracciabilità tra questi artefatti è critico per la manutenzione, l'analisi dell'impatto delle modifiche e l'evoluzione. Tuttavia, il mantenimento manuale dei collegamenti di tracciabilità (trace links) è laborioso ed erroneo. Sebbene il recupero automatizzato dei collegamenti di tracciabilità (Traceability Link Recovery - TLR) sia essenziale, gli approcci ARDoCo esistenti (SWATTR, ArCoTL, TransArC, LiSSA) sono stati storicamente disponibili solo come librerie Java o strumenti a riga di comando. Questa barriera tecnica ne impedisce l'adozione da parte di architetti e sviluppatori che non possiedono le competenze per configurare ed eseguire tali strumenti, limitando l'implementazione pratica del TLR allo stato dell'arte.

Metodologia e Panorama degli Strumenti
Per colmare il divario tra la ricerca algoritmica e l'applicazione pratica, gli autori presentano un panorama di strumenti distribuito pubblicamente composto da tre interfacce complementari che espongono la famiglia di TLR ARDoCo:

API REST ARDoCo: Un backend basato su Spring Boot che fornisce l'accesso programmatico a quattro pipeline di TLR tramite endpoint HTTP. Supporta l'esecuzione asincrona e il caching dei risultati (tramite Redis) per ottimizzare le prestazioni. Le pipeline esposte includono:
- SAD-SAM: Utilizzando SWATTR (NLP ed euristiche) con rilevamento di incongruenze di tipo "Text Entity Absent from Model" (TEAM) e "Model Entity Absent from Text" (MEAT).
- SAM-Code: Utilizzando ArCoTL (rappresentazioni intermedie e somiglianza testuale).
- SAD-Code (Diretto): Utilizzando ArDoCode (applicando le euristiche di SWATTR direttamente al codice senza un SAM).
- Transitivo SAD-SAM-Code: Utilizzando TransArC (componendo SWATTR e ArCoTL in modo transitivo).
  L'API restituisce JSON strutturato e include una Swagger UI integrata per l'esplorazione.
TraceView: Un frontend basato su browser, senza installazione, costruito con Next.js e React, ottimizzato per architetti e non sviluppatori. Presenta una procedura guidata (wizard) per il caricamento degli artefatti (SAD, SAM, codice) e la configurazione della pipeline di TLR. L'interfzione principale offre una vista interattiva multi-pannello dove gli utenti possono visualizzare SAD, SAM e codice sorgente affiancati. La selezione di un elemento evidenzia i corrispettivi collegati e le incongruenze rilevate in tutti i pannelli, facilitando la navigazione tra gli artefatti.
TraceViz: Un'estensione per Visual Studio Code ottimizzata per gli sviluppatori, specificamente per il TLR SAD-Code. Sovrappone i collegamenti di tracciabilità direttamente nell'IDE sotto forma di indicatori colorati nel margine (gutter markers). Caratteristiche chiave includono:
- Navigazione: Navigazione con un clic dalle frasi della documentazione ai file di codice collegati (e viceversa) tramite menu Quick Pick o CodeLens.
- Agnosticismo della Sorgente: Supporta collegamenti dall'API REST (ArDoCode/TransArC), importazioni CSV da strumenti esterni e l'esecuzione locale di LiSSA (un approccio di Retrieval-Augmented Generation).
- Ottimizzazione Visiva: Riduce il rumore aggregando i marcatori per file in punti a livello di directory quando appropriato e consente il confronto affiancato di fino a due set di collegamenti di tracciabilità.

Contributi Chiave

Accessibilità: Il panorama trasforma complessi algoritmi di TLR basati su librerie in strumenti accessibili che richiedono poca o nessuna installazione locale, rivolgendosi a diversi profili utente (integratori, architetti e sviluppatori).
Backend Unificato: L'API REST funge da motore computazionale condiviso, garantendo la coerenza tra l'interfaccia browser e quella IDE, abilitando al contempo l'integrazione con terze parti.
Visualizzazione In-IDE: TraceViz introduce un approccio innovativo alla visualizzazione della tracciabilità direttamente nel contesto di editing dello sviluppatore, andando oltre i report esterni.

Risultati e Valutazione

Prestazioni Algoritmiche: Gli algoritmi di TLR sottostanti sono stati valutati su un benchmark di cinque progetti Java open-source (MediaStore, TeaStore, TEAMMATES, BigBlueButton, JabRef). I risultati indicano che SWATTR raggiunge un F1 di 0,81 per SAD-SAM, ArCoTL raggiunge 0,98 per SAM-Code e TransArC raggiunge 0,82 per SAD-Code, superando significativamente il baseline di ArDoCode (F1 = 0,37). Il rilevamento delle incongruenze (MEAT) ha raggiunto un F1 di 0,89.
Studio Utente (TraceViz): Uno studio preliminare di tipo "think-aloud" ( $n=7$ $n = 7$ ) coinvolgente dottorandi, laureati magistrali e uno sviluppatore del settore ha valutato l'utilità di TraceViz. I partecipanti hanno eseguito compiti di comprensione del software sul progetto TEAMMATES con e senza visualizzazione.
- Sei partecipanti su sette hanno trovato la visualizzazione utile per il completamento del compito.
- Tutti i sette hanno concordato che supportava il loro processo di comprensione.
- Il feedback qualitativo ha indicato che, senza visualizzazione, gli utenti si affidavano a ripetitive traversate manuali dell'albero, mentre TraceViz permetteva salti diretti ai file rilevanti.
- Tre partecipanti hanno espresso l'intenzione di utilizzare lo strumento in contesti reali, mentre altri hanno notato il potenziale per l'onboarding e la navigazione in codebase di grandi dimensioni.

Significatività
Il paper sostiene che questo panorama di strumenti rende il TLR allo stato dell'arte accessibile a un pubblico più ampio di architetti, sviluppatori e integratori di strumenti che erano precedentemente esclusi dalla complessità tecnica degli algoritmi sottostanti. Fornendo uno strumento di esplorazione basato su browser (TraceView) e una visualizzazione integrata nell'IDE (TraceViz), gli autori dimostrano che la tracciabilità automatizzata può essere effettivamente implementata nella pratica. Lo studio utente preliminare suggerisce che visualizzare questi collegamenti direttamente nell'IDE migliora la comprensione e l'efficienza degli sviluppatori durante i compiti di comprensione del software. Il lavoro futuro mira a integrare approcci basati su LLM (LiSSA, ExArch) nel panorama e a condurre studi controllati più ampi.