Specifiche delle Analisi & Guida ai Concetti

Macondo è una suite ingegneristica di reverse engineering e analisi statica offline e deterministica per soluzioni software Visual Basic 6.0 e C# / .NET. Elabora i file sorgente direttamente senza richiedere runtime storici, registrazioni COM o dipendenze da IDE legacy.

Modello Formale del Grafo di Codice:

Cache Persistente su Disco: Al completamento dell'analisi, l'istantanea del grafo semantico e gli indici di impatto vengono salvati su disco in formato ottimizzato. I successivi avvii caricano istantaneamente in millisecondi con verifica automatica dei timestamp di modifica.

Macondo integra 4 algoritmi di layout specializzati per evidenziare topologie architetturali, gerarchie di dipendenza e domini isolati:

• Radiale Standard: Anelli orbitali concentrici che si irradiano verso l'esterno a partire dai punti di ingresso principali. Ideale per cogliere l'architettura complessiva.
• Radiale di Affinità: Anelli concentrici con attrazione angolare che raggruppa componenti frequentemente interagenti per minimizzare gli incroci di archi.
• Cluster a Isole: Raggruppa fisicamente l'architettura in isole funzionali segregate: Form UI, Moduli di Logica, Classi di Dominio e Controlli Utente.
• Force-Directed: Simula la repulsione elettrostatica tra nodi con forze a molla lungo le relazioni di chiamata (modello Fruchterman-Reingold), accentrando i nodi ad alto traffico.

Nodi Contenitore: File sorgente principali visualizzati come nodi macro con supporto all'espansione dinamica:

• Form (.frm): Blu (#4FA8E8) — Finestre e dialoghi dell'interfaccia utente.
• Moduli (.bas): Viola (#C084F0) — Logica procedurale globale e funzioni di utilità.
• Classi (.cls / .cs): Verde (#54C08C) — Entità di dominio, servizi e logica applicativa.
• Controlli Utente (.ctl): Arancione (#F08C4A) — Componenti grafici e controlli ActiveX riutilizzabili.

Nodi Membro & Routine: Sotto-nodi visualizzati espandendo un contenitore:

• Sub / Function: Grigio Slate (#7D7D8E) — Metodi eseguibili e routine procedurali.
• Property (Get / Let / Set): Oro (#E8B838) — Accessori incapsulati per i campi di stato.
• Campi / Variabili di Stato: Azzurro (#60A5FA) — Variabili di modulo e statiche.
• Costanti (Const): Corallo (#F87171) — Valori immutabili dichiarati.
• Tipi / Enum: Menta (#34D399) — User-Defined Types (UDT) ed enumerazioni.

Relazioni degli Archi Semantici:

• CALLS: Freccia verde acqua diretta dalla procedura chiamante verso la routine invocata.
• INSTANTIATES: Freccia ambra che indica la creazione di un'istanza (Set x = New Class o Dim x As New).
• USES_TYPE: Freccia lavanda che rappresenta dipendenze da parametri, campi o tipi di ritorno.

Mappa visiva che ricostruisce esaustivamente le transizioni tra interfacce grafiche e gli eventi del ciclo di vita dei form senza richiedere l'esecuzione dell'app.

Invocazioni UI Rilevate:

• Aperture & Istanze: .Show, Load Form e aperture modali (vbModal).
• Chiusure & Scaricamento: Chiamate a .Hide e istruzioni Unload Me.
• Catene di Schermate: Ricostruisce le sequenze di navigazione complete dal menu principale ai flussi di dialogo e conferma.

Decompone una singola Sub, Function o Property in un grafo orientato di Basic Block di istruzioni lineari e diramazioni condizionali.

Strutture di Controllo Mappate:

• Nodi Decisionali: If...Then...Else, Select Case.
• Cicli & Loop: For...Next, For Each, Do...While, While...Wend.
• Gestione Errori & Salti: On Error GoTo, Resume, etichette GoTo.

Fondamentale per analizzare logiche complesse "spaghetti code", individuare blocchi non raggiungibili e progettare test unitari completi.

Visualizzazione circolare a corde (Chord) che quantifica i volumi di interazione cross-layer e l'accoppiamento tra namespace e livelli architetturali.

• Spessore della Corda: Proporzionale al numero complessivo di chiamate tra componenti o package.
• Raggruppamento per Livelli: Organizza i componenti per layer (Presentazione UI, Dominio Applicativo, Persistenza Dati, Utilità).
• Rilevamento Violazioni: Evidenzia all'istante chiamate anomale che violano i confini architetturali (es. moduli di persistenza che invocano form grafici).

Trasforma l'intera codebase in una città tridimensionale interattiva ispirata alla metodologia di visualizzazione polimetrica di Wettel & Lanza:

• Distretti / Quartieri: Rappresentano cartelle, package o sotto-progetti architetturali.
• Edifici: Rappresentano singoli file, classi o moduli.
• Base dell'Edificio (Larghezza × Profondità): Proporzionale alle linee di codice effettive (LOC).
• Altezza dell'Edificio: Proporzionale alla Complessità Ciclomatica di McCabe.
• Colore dell'Edificio: Rispecchia il livello di rischio, frequenza di modifica (churn) o densità di debito tecnico.

Matrice adiacente quadrata \( N \times N \) che mappa ogni accoppiamento diretto e indiretto tra tutti i moduli del sistema software.

Identificazione dei Cicli tramite Tarjan:

Consente di individuare all'istante cluster ciclici ricorsivi e guidare il disaccoppiamento ordinato prima di avviare migrazioni a microservizi o architetture pulite.

Mappa gerarchica proporzionale basata sull'algoritmo Squarified Treemap per visualizzare la distribuzione volumetrica del codice:

• Superficie dei Rettangoli: Scalata in base alla metrica primaria selezionata (es. Linee di Codice, Numero di Membri, Volume di Halstead).
• Scala Cromatica: Riflette la metrica secondaria (es. Complessità Ciclomatica media o Indice di Manutenibilità).
• Permette di individuare a colpo d'occhio file sovradimensionati che concentrano la maggior parte della complessità del sistema.

Valuta il bilanciamento architetturale, la stabilità e il livello di astrazione di package e moduli secondo i principi SOLID:

Identifica componenti nella "Zona di Dolore" (iper-stabili ma concreti, rigidi al cambiamento) e nella "Zona di Inutilità" (iper-astratti ma privi di utilizzatori concreti).

Misura il grado di coesione interna dei metodi di una classe in base all'accesso ai campi di stato d'istanza condivisi:

Valutazione quantitativa della manutenibilità del codice (scala 0–100) calcolata secondo la formula standard del Software Engineering Institute (SEI):

Soglie di Manutenibilità: > 85: Alta (Verde) | 65–85: Moderata (Giallo) | < 65: Bassa, alto debito tecnico (Rosso).

Motore dichiarativo di conformità architetturale che verifica sistematicamente il rispetto dei vincoli tra livelli del software:

• Verifica regole personalizzate (es. "Il layer di presentazione non deve accedere direttamente alle tabelle del database").
• Rileva importazioni vietate, bypass di strati intermedi (Layer Skipping) e accoppiamenti anomali.
• Eseguibile in modalità automatica per bloccare build non conformi nei flussi di integrazione continua (CI/CD).

Tracciamento ricorsivo deterministico di tutti i chiamanti a monte (upstream callers) per calcolare l'impatto di modifica su una routine o proprietà prima di toccare il codice:

• Basso Rischio (Verde): Modifiche locali a routine foglia senza dipendenze multiple.
• Medio Rischio (Giallo): Impatto limitato a un singolo modulo o form.
• Alto / Critico (Rosso): Routine centrale invocata trasversalmente da decine di form e classi.

Scatter plot 2D che correla la Complessità Ciclomatica interna con il Fan-In strutturale e la frequenza di modifica (Churn) per isolare i punti di massima fragilità:

• Isola routine con elevata complessità e altissimo numero di chiamanti, priorità assolute per refactoring e test di regressione.
• Genera un elenco graduato per severità con raccomandazioni mirate di scomposizione.

Analisi di raggiungibilità globale su tutto il grafo delle chiamate per individuare elementi non utilizzati:

• Rileva Sub, Function, Property, Costanti e Form dichiarati ma mai invocati da alcun punto di ingresso attivo.
• Filtra automaticamente handler di eventi GUI standard di VB6 (es. Form_Load, Command1_Click) per evitare falsi positivi.
• Quantifica il volume di righe di codice eliminabili prima di avviare migrazioni software.

Mappatura completa di tutte le variabili Public e Global dichiarate nei moduli standard con tracciamento di chi legge e chi scrive:

• Identifica variabili globali ad alta densità di scrittura da punti disgiunti del codice.
• Evidenzia potenziale corruzione silenziosa dello stato e precondizioni per refactoring a pattern moderni (Dependency Injection).

Analizza la cronologia dei commit Git per rilevare file che cambiano sistematicamente insieme pur non avendo una dipendenza sintattica formale:

Un valore elevato rivela accoppiamenti logici nascosti o duplicazioni di regole di business tra componenti non collegati.

Algoritmo a tokenizzazione e rolling hash per identificare duplicazioni strutturali di codice:

• Cloni di Tipo 1: Blocchi di codice identici (spazi e commenti ignorati).
• Cloni di Tipo 2: Blocchi identici con identificatori, nomi di variabili o tipi rinominati.
• Cloni di Tipo 3: Blocchi con lievi modifiche o istruzioni aggiunte/rimosse.

Traccia la propagazione di input esterni e variabili utente (Sources) verso query SQL, API di sistema o comandi di shell (Sinks):

• Verifica la presenza di routine di validazione o sanificazione lungo i percorsi di dati.
• Rileva vulnerabilità di sicurezza (SQL Injection, Command Injection) e flussi di dati non convalidati.

Mappa incrociata delle operazioni di database (Create, Read, Update, Delete) estratte dalle query SQL statiche e chiamate ADODB/DAO:

• Associa a ciascuna tabella o entità tutte le routine applicative che vi accedono.
• Evidenzia entità orfane (scritte ma mai lette) e tabelle critiche soggette a continue mutazioni.

Confronto semantico tra l'interfaccia pubblica di due versioni del progetto:

• Breaking Change (Major): Rimozione di metodi pubblici, modifica dei tipi di parametro o del tipo di ritorno.
• Non-Breaking (Minor): Aggiunta di nuovi metodi o proprietà pubbliche compatibili.
• Patch: Modifiche interne all'implementazione senza alterare le firme pubbliche.

Incrocia l'albero del codice con la storia dei commit Git per calcolare la dispersione della conoscenza:

• Calcola la proprietà del codice (Code Ownership) per ciascun modulo.
• Stima il Bus Factor: il numero minimo di sviluppatori la cui assenza comporterebbe la perdita di conoscenza critica sul progetto.

Macondo supporta l'esecuzione headless da riga di comando per automatizzare quality gate e audit nelle pipeline CI/CD (GitHub Actions, Azure DevOps, GitLab CI):

• Esporta report completi in formato Markdown, JSON, SVG vettoriale e CSV.
• Restituisce codici di uscita conformi per bloccare automaticamente le pipeline di build in caso di violazione delle soglie di qualità.