# Manuale Utente PyUCC **Versione Documento:** 1.0 **Applicazione:** PyUCC (Python Unified Code Counter) --- ## 1. Introduzione **PyUCC** è uno strumento avanzato per l'analisi statica del codice sorgente. Il suo obiettivo principale è fornire metriche quantitative sullo sviluppo software e, soprattutto, tracciare l'evoluzione del codice nel tempo attraverso un potente sistema di *Differing* (confronto). ### A cosa serve? 1. **Contare:** Sapere quante righe di codice, commenti e righe vuote compongono il tuo progetto. 2. **Misurare:** Calcolare la complessità e la manutenibilità del software. 3. **Confrontare:** Capire esattamente cosa è cambiato tra due versioni (file aggiunti, rimossi, modificati e come la complessità è variata). --- ## 2. Concetti Fondamentali Prima di iniziare, è utile comprendere i termini chiave utilizzati nell'applicazione. ### 2.1 Baseline Una **Baseline** è una "fotografia" istantanea del tuo progetto in un preciso momento. * Quando crei una baseline, PyUCC salva una copia dei file e calcola tutte le metriche. * Le baseline servono come punto di riferimento (o "pietra di paragone") per i confronti futuri. ### 2.2 Metriche Supportate * **SLOC (Source Lines of Code):** * *Physical Lines:* Totale righe del file. * *Code Lines:* Righe che contengono codice eseguibile. * *Comment Lines:* Righe di documentazione. * *Blank Lines:* Righe vuote (spesso usate per formattazione). * **Complessità Ciclomatica (CC):** Misura quanto è complesso il flusso di controllo (quanti `if`, `for`, `while`, ecc.). Più è bassa, meglio è. * **Maintainability Index (MI):** Un indice da 0 a 100 che stima quanto il codice sia facile da mantenere. Più è alto, meglio è (sopra 85 è ottimo, sotto 65 è problematico). ### 2.3 Profilo Un **Profilo** è una configurazione salvata che dice a PyUCC: * Quali cartelle analizzare. * Quali linguaggi includere (es. solo Python e C++). * Cosa ignorare (es. cartelle `venv`, `build`, file temporanei). --- ## 3. Interfaccia Utente (GUI) L'interfaccia è divisa in zone funzionali per mantenere il flusso di lavoro ordinato. 1. **Top Bar (Barra Superiore):** * Selezione del **Profilo**. * Accesso alle impostazioni (**Settings**) e gestione profili (**Manage**). 2. **Actions Bar (Azioni):** I pulsanti principali per avviare le operazioni (`Scan`, `Countings`, `Metrics`, `Differing`). 3. **Progress Area:** Barra di avanzamento e contatore dei file elaborati. 4. **Results Table:** La grande tabella centrale dove appaiono i dati. 5. **Log & Status:** In basso, un pannello di log per vedere cosa sta succedendo e una barra di stato con il monitoraggio risorse (CPU/RAM). --- ## 4. Guida Passo-Passo ### 4.1 File di Configurazione e Posizione PyUCC salva tutte le sue configurazioni in file JSON nella stessa cartella dell'eseguibile, rendendo il software completamente portatile. **File di configurazione:** - **`profiles.json`**: Contiene tutti i profili di analisi salvati (percorsi, filtri, impostazioni). - **`settings.json`**: Contiene le impostazioni globali dell'applicazione (cartella baseline, duplicati, ecc.). **Posizione:** - **Esecuzione da eseguibile**: I file si trovano nella stessa cartella di `pyucc.exe` - **Esecuzione da sorgente**: I file si trovano nella cartella radice del progetto (accanto a `README.md`) Questi file vengono creati automaticamente al primo avvio dell'applicazione. Se non esistono, PyUCC utilizza valori predefiniti. ### 4.2 Impostazioni dell'Applicazione (settings.json) Per configurare correttamente PyUCC al primo avvio, è importante comprendere le impostazioni disponibili: **`baseline_dir` (Cartella Baseline)** - **Cosa fa**: Specifica dove vengono salvate le baseline (snapshot del progetto per i confronti). - **Predefinito**: `./baseline` (nella cartella dell'eseguibile) - **Come configurare**: - Vai su **⚙️ Settings** → **Baseline Directory** - Scegli una cartella dedicata (es. `C:\MyProjects\baselines`) - **Quando configurare**: Al primo avvio, soprattutto se hai più progetti da analizzare - **Consiglio**: Usa una cartella separata per ogni progetto o una cartella centrale con sottocartelle **`max_keep` (Massime Baseline da Mantenere)** - **Cosa fa**: Numero massimo di baseline da conservare per ogni profilo. - **Predefinito**: 10 - **Come configurare**: Vai su **⚙️ Settings** → **Max Baseline To Keep** - **Quando configurare**: Se lavori su progetti grandi o hai poco spazio disco - **Consiglio**: 5-10 per progetti piccoli, 20-30 per progetti grandi con molte release **`zip_baselines` (Comprimi Baseline)** - **Cosa fa**: Comprime automaticamente le baseline per risparmiare spazio. - **Predefinito**: `true` - **Come configurare**: Vai su **⚙️ Settings** → checkbox **Zip Baselines** - **Quando configurare**: Lascia abilitato a meno che non abbia problemi di performance - **Consiglio**: Tienilo attivo, riduce l'uso del disco del 70-90% **Impostazioni Duplicati (`duplicates_settings`)** - **`threshold`** (Soglia di Similarità Fuzzy): 0.0-1.0, default 0.85 - Valori più alti = meno falsi positivi, ma potrebbero perdere duplicati reali - Valori più bassi = più duplicati trovati, ma più falsi positivi - **`k`** (K-gram Size): 3-10, default 5 - K-gram più grandi = meno sensibile a piccole modifiche - K-gram più piccoli = più sensibile a piccole modifiche - **`window`** (Finestra Winnowing): 3-20, default 4 - Finestre più grandi = meno hash da confrontare (più veloce ma meno preciso) - Finestre più piccole = più hash da confrontare (più lento ma più preciso) **Come configurare i duplicati:** 1. Vai su **⚙️ Settings** → **Duplicates Detection** 2. Regola i parametri in base alle tue esigenze 3. Fai test con diversi valori sul tuo codice **Raccomandazioni per il primo avvio:** 1. **Configura `baseline_dir`** prima di creare la prima baseline 2. Lascia gli altri valori predefiniti e regolali solo se necessario 3. Le impostazioni si applicano a tutti i profili ### 4.3 Configurazione Profilo Non appena apri PyUCC, la prima cosa da fare è dire al programma *cosa* analizzare. 1. Clicca su **⚙️ Manage...** in alto. 2. Clicca su **📝 New** per pulire i campi. 3. Inserisci un **Nome** per il profilo (es. "Mio Progetto Backend"). 4. Nella sezione **Paths**, usa **Add Folder** per selezionare la cartella radice del tuo codice. 5. Nella sezione **Filter Extensions**, seleziona i linguaggi che ti interessano (es. Python, Java). 6. Nella casella **Ignore patterns**, puoi lasciare i default (che escludono già `.git`, `__pycache__`, ecc.). 7. Clicca **💾 Save**. ### 4.4 Analisi Semplice (Scan, Countings, Metrics) Se vuoi solo analizzare lo stato attuale senza confronti: * **🔍 Scan:** Verifica semplicemente quali file vengono trovati in base ai filtri del profilo. Utile per controllare se stai includendo i file giusti. * **🔢 Countings:** Analizza ogni file e ti dice quante righe di codice, commenti e vuote ci sono. * **📊 Metrics:** Calcola la complessità ciclomatica e l'indice di manutenibilità per ogni file. > **Tip:** Puoi fare doppio click su un file nella tabella dei risultati per aprirlo nel **File Viewer** integrato, che evidenzia la sintassi e mostra una minimappa colorata (blu=codice, verde=commenti). ### 4.5 Il Flusso di Lavoro "Differing" (Confronto) Questa è la funzione più potente di PyUCC. **Passo A: Creare la prima Baseline** 1. Seleziona il tuo profilo. 2. Clicca su **🔀 Differing**. 3. Se è la prima volta che analizzi questo progetto, PyUCC ti avviserà: *"No baseline found"*. 4. Conferma la creazione. PyUCC scatterà una "foto" del progetto (Baseline). **Passo B: Lavorare sul codice** Ora puoi chiudere PyUCC e lavorare al tuo codice (modificare file, aggiungerne, cancellarne). **Passo C: Confrontare** 1. Riapri PyUCC e seleziona lo stesso profilo. 2. Clicca su **🔀 Differing**. 3. Questa volta, PyUCC vedrà che esiste una Baseline precedente e ti chiederà con quale confrontare (se ne hai più di una). 4. Il risultato sarà una tabella con colori specifici: * **Verde:** File aggiunti o metriche migliorate. * **Rosso:** File cancellati o metriche peggiorate (es. complessità aumentata). * **Giallo/Arancio:** File modificati. * **Colonne Δ (Delta):** Mostrano la differenza numerica (es. `+50` righe di codice, `-2` complessità). > **Visualizzatore Differenze:** Se fai doppio click su una riga nel risultato del Differing, si aprirà una finestra che mostra i due file affiancati, evidenziando esattamente le righe cambiate. --- ## 5. Casi d'Uso Esemplificativi ### Caso 1: Refactoring del codice * **Obiettivo:** Vuoi pulire il codice e assicurarti di non aver aumentato la complessità. * **Azione:** Fai una Baseline prima di iniziare. Fai il refactoring. Esegui il *Differing*. * **Verifica:** Controlla la colonna **Δ avg_cc**. Se è negativa (es. `-0.5`), ottimo! Hai ridotto la complessità. Se la colonna **Δ comment_lines** è positiva, hai migliorato la documentazione. ### Caso 2: Code Review * **Obiettivo:** Un collega ha aggiunto una nuova feature. Cosa è cambiato? * **Azione:** Esegui il *Differing* rispetto alla versione master precedente. * **Verifica:** Ordina per "Status". Vedi subito i file **Added** (A) e **Modified** (M). Apri il Diff Viewer sui file modificati per vedere le righe esatte. --- ## 6. Filosofia di Sviluppo (Per Sviluppatori) PyUCC è stato scritto seguendo principi di ingegneria del software rigorosi, che si riflettono nella stabilità dell'uso. ### 6.1 Codice Pulito e Standard PEP8 Il codice rispetta lo standard **PEP8** di Python. Questo garantisce che, se un giorno volessi estendere il tool o scriverne degli script di automazione usando i moduli `core`, troveresti un codice leggibile, standardizzato e prevedibile. ### 6.2 Separazione delle Responsabilità (SoC) L'applicazione è divisa nettamente in due parti: 1. **Core (`pyucc.core`):** Contiene la logica pura (scansione, calcolo metriche, algoritmi di diff). Non sa nulla dell'interfaccia grafica. 2. **GUI (`pyucc.gui`):** Gestisce solo la visualizzazione. **Filosofia:** Questo permette di cambiare la grafica senza rompere la logica, o usare la logica da riga di comando senza avviare la grafica. ### 6.3 Non-Blocking UI (Worker Manager) Hai notato che l'interfaccia non si blocca mai, anche analizzando migliaia di file? Questo è grazie al **WorkerManager**. Tutte le operazioni pesanti vengono eseguite in thread separati (background). L'interfaccia grafica riceve aggiornamenti tramite una coda sicura (`queue`). * **Per l'utente significa:** Puoi sempre premere "Cancel" se un'operazione è troppo lunga. ### 6.4 Algoritmo di Matching Intelligente (Gale-Shapley) Nel *Differing*, PyUCC non guarda solo se il nome del file è identico. Usa un algoritmo ispirato al "problema del matrimonio stabile" (Gale-Shapley) combinato con la distanza di Levenshtein sui percorsi. * **Filosofia:** Se sposti un file da una cartella all'altra, il sistema cerca di capire che è lo stesso file spostato, invece di segnarne uno come "Deleted" e uno come "Added". ### 6.5 Determinismo Il sistema usa l'hashing (SHA1/MD5) del contenuto dei file per ottimizzare i calcoli (caching) e per determinare se un file è *veramente* cambiato, ignorando la data di modifica del file system se il contenuto è identico. --- ## 7. Risoluzione Problemi Comuni * **Il programma non trova file:** Controlla nel Profile Manager se l'estensione del file è nella lista dei linguaggi o se la cartella è inclusa negli "Ignore patterns". * **Lentezza estrema:** Se hai incluso cartelle con migliaia di file piccoli non di codice (es. `node_modules` o cartelle di immagini), aggiungile agli "Ignore patterns". * **Diff Viewer vuoto:** Assicurati che i file sorgente esistano ancora sul disco. Se hai cancellato la cartella del progetto dopo aver fatto la baseline, il viewer non potrà mostrare il file corrente. --- ## 8. Nuove Funzionalità (Da v1.0) Questa release introduce funzionalità che migliorano l'analisi della qualità del codice, la riproducibilità delle baseline e la ricerca di duplicazioni nel codice. Di seguito una descrizione sintetica delle novità e come usarle. ### 8.1 Rilevamento Duplicati (GUI + CLI) - **Cosa fa:** Individua duplicati esatti e fuzzy all'interno del progetto. I duplicati esatti sono individuati tramite hashing del contenuto (SHA1). I duplicati fuzzy usano fingerprinting a k-gram con una fase di winnowing e una misura di similarità Jaccard per identificare coppie simili. - **Parametri:** `k` (dimensione dei k-gram), `window` (finestra di winnowing) e `threshold` (soglia di similarità in percentuale). I valori di default sono bilanciati per precisione/recall ma possono essere modificati dall'utente. - **Esecuzione (GUI):** Usa il nuovo pulsante **Duplicates** nella barra Azioni (posizionato prima del pulsante Differ). Una finestra di dialogo permette di scegliere estensioni, soglia e parametri di fingerprinting. Le impostazioni sono persistenti. - **Esecuzione (CLI):** `python -m pyucc duplicates --threshold 5.0 --ext .py .c` stampa in output JSON i duplicati trovati. - **Esportazione:** Risultati esportabili in `CSV` e in un report testuale in stile UCC inserito nella cartella baseline (quando eseguito durante la creazione della baseline). ### 8.2 Report UCC-style per Duplicati e Differenze - **Tabella compatta in stile UCC:** Il differ ora può generare una tabella compatta simile all'output UCC, con colonne Δ (delta) aggiuntive: `ΔCode`, `ΔComm`, `ΔBlank`, `ΔFunc`, `ΔAvgCC`, `ΔMI`, per vedere rapidamente le variazioni numeriche. - **Report duplicati:** Viene creato un file testuale `duplicates_report.txt` (se richiesto) che elenca i gruppi di duplicati con la similarità percentuale e i parametri usati. Le baseline salvano i parametri per garantire la riproducibilità. Esempio (snippet compatto in stile UCC): ``` File Code Comm Blank Func AvgCC MI ΔCode ΔComm ΔBlank ΔFunc ΔAvgCC ΔMI --------------------------------------------------------------------------------------------------------------- src/module/a.py 120 10 8 5 2.3 78 +10 -1 0 +0 -0.1 +2 src/module/b_copy.py 118 8 10 5 2.4 76 -2 -2 +2 0 +0.1 -2 ``` ### 8.3 Scanner e Migliorie alle Baseline - **Scansione centralizzata:** Lo `scanner` è il fornitore canonico della lista file. Moduli pesanti (Differ, Duplicates) possono ricevere la `file_list` prodotta dallo scanner per evitare ricerche ripetute e garantire lo stesso filtro. - **Normalizzazione dei pattern di ignore:** Voci di ignore come `.bak` vengono normalizzate in `*.bak` e il matching è case-insensitive per default; questo evita di includere file di backup nelle baseline. - **Riproducibilità delle baseline:** Le baseline memorizzano i parametri usati per la ricerca duplicati e la lista dei file snapshot. Se in seguito viene installato `lizard`, PyUCC tenta di rieseguire l'analisi per ottenere informazioni sulle funzioni anche nelle baseline create in precedenza. ### 8.4 Note sulle Dipendenze - Le metriche a livello di funzione (numero di funzioni, CC per funzione) richiedono `lizard`. Se `lizard` non è installato, PyUCC produrrà comunque SLOC e metriche di base, ma i dettagli per funzione potrebbero mancare. La creazione della baseline registra questo stato e tenterà una rianalisi se `lizard` diventa disponibile. --- ## 9. Rilevamento Duplicati: Algoritmi e Dettagli Tecnici Questa sezione fornisce una comprensione più approfondita di come PyUCC identifica il codice duplicato, cosa fanno gli algoritmi e come interpretare i risultati. ### 9.1 Rilevamento Duplicati Esatti **Come funziona:** - PyUCC normalizza ciascun file (rimuove spazi iniziali/finali da ogni riga, converte in minuscolo opzionalmente). - Calcola un hash SHA1 del contenuto normalizzato. - I file con hash identici sono considerati duplicati esatti. **Caso d'uso:** Trovare file che sono stati copiati e incollati senza o con modifiche minime (es. `utils.py` e `utils_backup.py`). **Cosa vedrai:** - Nella tabella GUI: coppie di file contrassegnate come duplicati "esatti" con similarità al 100%. - Nel report: elencate nella sezione "Duplicati esatti". ### 9.2 Rilevamento Duplicati Fuzzy (Avanzato) Il rilevamento fuzzy identifica file che sono *simili* ma non identici. È utile per trovare: - Codice che è stato copiato e poi leggermente modificato. - Moduli rifatti che condividono grandi blocchi di logica. - Branch sperimentali o "quasi-duplicati" che dovrebbero essere fusi. **Panoramica dell'Algoritmo:** 1. **Hashing K-gram (Rolling Hash con Rabin-Karp):** - Ogni file è diviso in sequenze sovrapposte di `k` righe consecutive (k-gram). - Viene calcolato un rolling hash (hash polinomiale Rabin-Karp) per ogni k-gram. - Questo produce un grande insieme di valori hash che rappresentano tutti i k-gram del file. 2. **Winnowing (Selezione delle Impronte Digitali):** - Per ridurre il numero di hash (e migliorare le prestazioni), PyUCC applica una tecnica di "winnowing". - Una finestra scorrevole di dimensione `w` si sposta sulla sequenza di hash. - In ogni finestra, viene selezionato il valore hash minimo come impronta digitale. - Questo crea un insieme compatto di impronte rappresentative per il file. - **Proprietà chiave:** Se due file condividono una sottostringa di almeno `k + w - 1` righe, condivideranno almeno un'impronta digitale. 3. **Indice Invertito:** - Tutte le impronte digitali di tutti i file vengono memorizzate in un indice invertito: `{impronta -> [lista di file che la contengono]}`. - Questo permette una ricerca veloce di quali file condividono impronte. 4. **Similarità di Jaccard:** - Per ogni coppia di file che condividono almeno un'impronta digitale, PyUCC calcola la similarità di Jaccard: ``` Jaccard(A, B) = |A ∩ B| / |A ∪ B| ``` - Dove A e B sono gli insiemi di impronte digitali per i due file. - Se il punteggio Jaccard è sopra la soglia (default: 0.85, ovvero 85% di similarità), la coppia viene segnalata come duplicato fuzzy. 5. **Calcolo Percentuale di Modifica:** - PyUCC stima anche la percentuale di righe che differiscono tra i due file. - Se `pct_change <= threshold` (es. ≤5%), i file sono considerati duplicati. **Parametri regolabili:** - **`k` (dimensione k-gram):** Numero di righe consecutive in ogni k-gram. Default: 25. - `k` maggiore → meno falsi positivi, ma può perdere duplicati piccoli. - `k` minore → più sensibile, ma può produrre falsi positivi. - **`window` (dimensione finestra winnowing):** Dimensione della finestra per selezionare le impronte. Default: 4. - Finestra maggiore → meno impronte, elaborazione più veloce, ma può perdere alcune corrispondenze. - Finestra minore → più impronte, più lento, ma più accurato. - **`threshold` (soglia percentuale di modifica):** Differenza massima consentita (in %) per considerare ancora due file come duplicati. Default: 5.0%. - Soglia inferiore → corrispondenza più stretta (solo file molto simili). - Soglia superiore → più permissiva (cattura file con più differenze). **Impostazioni consigliate:** | Caso d'Uso | k | window | threshold | |----------|---|--------|----------| | Ricerca duplicati stretta (solo file quasi identici) | 30 | 5 | 3.0% | | Bilanciata (default) | 25 | 4 | 5.0% | | Corrispondenza lassa (cattura codice rifatto) | 20 | 3 | 10.0% | | Molto aggressiva (sperimentale) | 15 | 2 | 15.0% | ### 9.3 Interpretare i Report sui Duplicati **Colonne Tabella GUI:** - **File A / File B:** I due file confrontati. - **Match Type:** "exact" o "fuzzy". - **Similarity (%):** Per corrispondenze fuzzy, il punteggio di similarità Jaccard (0-100%). - **Pct Change (%):** Percentuale stimata di righe che differiscono. **Report Testuale (duplicates_report.txt):** Il report è diviso in due sezioni: 1. **Duplicati Esatti:** ``` Exact duplicates: 3 src/utils.py <=> src/backup/utils_old.py src/module/helper.py <=> src/module/helper - Copy.py ``` 2. **Duplicati Fuzzy:** ``` Fuzzy duplicates (threshold): 5 src/processor.py <=> src/processor_v2.py Similarity: 92.5% | Pct Change: 3.2% src/core/engine.py <=> src/experimental/engine_new.py Similarity: 88.0% | Pct Change: 4.8% ``` **Interpretazione:** - **Alta similarità (>95%):** Forti candidati per la deduplicazione. Considera di mantenere solo una versione o di fonderle. - **Media similarità (85-95%):** Rivedi manualmente. Può indicare codice rifatto o variazioni intenzionali. - **Violazioni della soglia:** I file che superano la soglia `pct_change` non appariranno nel report, anche se condividono alcune impronte. --- ## 10. Leggere e Interpretare i Report Differ La funzionalità Differ produce diversi tipi di output. Comprendere ciascuno aiuta a tracciare l'evoluzione del codice con precisione. ### 10.1 Tabella Compatta in Stile UCC Quando esegui *Differing*, PyUCC genera una tabella di riepilogo compatta simile allo strumento UCC originale: **Esempio:** ``` File Code Comm Blank Func AvgCC MI ΔCode ΔComm ΔBlank ΔFunc ΔAvgCC ΔMI --------------------------------------------------------------------------------------------------------------- src/module/a.py 120 10 8 5 2.3 78 +10 -1 0 +0 -0.1 +2 src/module/b.py 118 8 10 5 2.4 76 -2 -2 +2 0 +0.1 -2 src/new_feature.py 45 5 3 2 1.8 82 +45 +5 +3 +2 +1.8 +82 src/old_code.py -- -- -- -- -- -- -30 -5 -2 -1 -2.1 -75 ``` **Significato delle Colonne:** | Colonna | Significato | |--------|--------| | **File** | Percorso relativo del file | | **Code** | Numero corrente di righe di codice | | **Comm** | Numero corrente di righe di commenti | | **Blank** | Numero corrente di righe vuote | | **Func** | Numero di funzioni rilevate (richiede `lizard`) | | **AvgCC** | Complessità ciclomatica media per funzione | | **MI** | Indice di Manutenibilità (0-100, più alto è meglio) | | **ΔCode** | Variazione nelle righe di codice (corrente - baseline) | | **ΔComm** | Variazione nelle righe di commenti | | **ΔBlank** | Variazione nelle righe vuote | | **ΔFunc** | Variazione nel conteggio funzioni | | **ΔAvgCC** | Variazione nella complessità ciclomatica media | | **ΔMI** | Variazione nell'indice di manutenibilità | **Codifica Colori (GUI):** - **Righe verdi:** File nuovi (Aggiunti) o metriche migliorate (es. ΔAvgCC < 0, ΔMI > 0). - **Righe rosse:** File eliminati o metriche peggiorate (es. ΔAvgCC > 0, ΔMI < 0). - **Righe gialle/arancioni:** File modificati con cambiamenti misti. - **Righe grigie:** File non modificati (identici alla baseline). **Cosa cercare:** - **ΔCode >> 0:** Espansione significativa del codice. È giustificata da nuove funzionalità? - **ΔComm < 0:** Documentazione diminuita. Considera di aggiungere più commenti. - **ΔAvgCC > 0:** Complessità aumentata. Può indicare necessità di refactoring. - **ΔMI < 0:** Manutenibilità peggiorata. Rivedi le modifiche. - **Nuovi file con alto AvgCC:** Il nuovo codice è già complesso. Segnala per revisione. ### 10.2 Report Diff Dettagliato (diff_report.txt) Un report testuale viene salvato nella cartella baseline: **Struttura:** ``` PyUCC Baseline Comparison Report ================================= Baseline ID: MyProject__20251205T143022_local Snapshot timestamp: 2025-12-05 14:30:22 Summary: New files: 3 Deleted files: 1 Modified files: 12 Unchanged files: 45 Metric Changes: Total Code Lines: +150 Total Comments: -5 Average CC: +0.2 (slight increase in complexity) Average MI: -1.5 (slight decrease in maintainability) [Tabella compatta in stile UCC qui] Legend: A = Added file D = Deleted file M = Modified file U = Unchanged file ... ``` ### 10.3 Esportazioni CSV Puoi esportare qualsiasi tabella dei risultati in CSV per ulteriori analisi in Excel, pandas o strumenti BI. **Le colonne includono:** - Percorso file - Tutte le metriche SLOC (codice, commenti, righe vuote) - Metriche di complessità (CC, MI, conteggio funzioni) - Delta (se da un'operazione Differ) - Flag di stato (A/D/M/U) **Casi d'uso:** - Analisi dei trend su più baseline. - Generazione di grafici (es. complessità nel tempo). - Integrazione in gate di qualità CI/CD. --- ## 11. Casi d'Uso Pratici e Workflow ### Caso d'Uso 1: Rilevare Codice Copiato Prima della Code Review **Scenario:** Il tuo team sta sviluppando un nuovo modulo. Sospetti che alcuni sviluppatori abbiano copiato e incollato codice esistente invece di fare refactoring. **Workflow:** 1. Crea un profilo per il tuo progetto. 2. Clicca sul pulsante **Duplicates**. 3. Imposta threshold a 5% (stretto). 4. Rivedi la tabella dei risultati. 5. Per ogni coppia di duplicati fuzzy: - Fai doppio click per aprire entrambi i file nel visualizzatore diff (se implementato). - Valuta se la duplicazione è intenzionale o dovrebbe essere rifatta in un'utility condivisa. 6. Esporta in CSV e condividi con il team per discussione. **Risultato atteso:** Identifichi 3-5 file quasi duplicati e crei ticket per consolidarli. --- ### Caso d'Uso 2: Tracciare la Complessità Durante uno Sprint di Refactoring **Scenario:** Il tuo team pianifica uno sprint di refactoring di 2 settimane per ridurre il debito tecnico. **Workflow:** 1. **Prima dello sprint:** Crea una baseline ("Pre-Refactor"). - Clicca **Differing** → Crea baseline. - Nominala "PreRefactor_Sprint5". 2. **Durante lo sprint:** Gli sviluppatori rifanno il codice, estraggono funzioni, aggiungono commenti. 3. **Dopo lo sprint:** Esegui **Differing** contro la baseline. 4. Rivedi la tabella compatta: - Controlla ΔAvgCC: Dovrebbe essere negativo (complessità ridotta). - Controlla ΔMI: Dovrebbe essere positivo (manutenibilità migliorata). - Controlla ΔComm: Dovrebbe essere positivo (più documentazione). 5. Genera un report diff e allegalo alla retrospettiva dello sprint. **Risultato atteso:** Prova quantitativa che il refactoring ha funzionato: "Abbiamo ridotto il CC medio del 15% e aumentato MI di 8 punti." --- ### Caso d'Uso 3: Assicurare che Nuove Funzionalità Non Degradino la Qualità **Scenario:** Stai aggiungendo una nuova funzionalità a una codebase matura. Vuoi assicurarti che il nuovo codice non introduca complessità eccessiva. **Workflow:** 1. Crea una baseline prima di iniziare lo sviluppo della funzionalità. 2. Sviluppa la funzionalità in un branch. 3. Prima del merge su main: - Esegui **Differing** per confrontare lo stato corrente vs. baseline. - Filtra per nuovi file (status = "A"). - Controlla AvgCC e MI dei nuovi file. - Se AvgCC > 5 o MI < 70, segnala per refactoring prima del merge. 4. Usa **Duplicates** per assicurarti che il nuovo codice non duplichi utility esistenti. **Risultato atteso:** Il codice della nuova funzionalità supera i gate di qualità prima del merge. --- ### Caso d'Uso 4: Generare Report di Conformità per Audit **Scenario:** La tua organizzazione richiede audit periodici sulla qualità del codice. **Workflow:** 1. Crea baseline mensili (es. "Audit_2025_01", "Audit_2025_02", ...). 2. Ogni baseline genera automaticamente: - `countings_report.txt` - `metrics_report.txt` - `duplicates_report.txt` 3. Archivia questi report in una cartella di conformità. 4. Per l'audit, fornisci: - Trend di SLOC totale nel tempo. - Trend di CC e MI medi. - Numero di duplicati rilevati e risolti ogni mese. **Risultato atteso:** Gli auditor vedono un miglioramento misurabile nelle metriche di qualità del codice nel tempo. --- ### Caso d'Uso 5: Onboarding Nuovi Sviluppatori con Metriche del Codice **Scenario:** Un nuovo sviluppatore si unisce al team e ha bisogno di comprendere la codebase. **Workflow:** 1. Esegui **Metrics** sull'intera codebase. 2. Esporta in CSV. 3. Ordina per AvgCC (decrescente) per identificare i moduli più complessi. 4. Condividi l'elenco con il nuovo sviluppatore: - "Questi 5 file hanno la complessità più alta. Fai particolare attenzione quando li modifichi." - "Questi moduli hanno MI basso. Sono candidati per refactoring—buoni esercizi di apprendimento." 5. Usa **Duplicates** per mostrare quali parti del codice hanno ridondanza (spiega perché). **Risultato atteso:** Il nuovo sviluppatore comprende più velocemente i punti critici e i problemi di qualità del codice. --- ## 12. Suggerimenti per un Uso Efficace ### 12.1 Gestione Profili - **Crea profili separati** per diversi sottoprogetti o componenti. - Usa **pattern di ignore** in modo aggressivo per escludere: - `node_modules`, `venv`, `.venv` - Output di build (`build/`, `dist/`, `bin/`) - Codice generato - Fixture di test o dati mock ### 12.2 Strategia Baseline - **Convenzione di denominazione:** Usa nomi descrittivi con date o tag di versione: - `Release_v1.2.0_20251201` - `PreRefactor_Sprint10` - `BeforeMerge_FeatureX` - **Frequenza:** Crea baseline ai traguardi chiave: - Fine di ogni sprint - Prima/dopo refactoring importanti - Prima dei rilasci - **Ritenzione:** Mantieni almeno 3-5 baseline recenti. Archivia quelle più vecchie. ### 12.3 Interpretare le Metriche **Complessità Ciclomatica (CC):** - **1-5:** Semplice, basso rischio. - **6-10:** Complessità moderata, accettabile. - **11-20:** Alta complessità, revisione raccomandata. - **21+:** Complessità molto alta, refactoring fortemente raccomandato. **Indice di Manutenibilità (MI):** - **85-100:** Altamente manutenibile (zona verde). - **70-84:** Moderatamente manutenibile (zona gialla). - **Sotto 70:** Bassa manutenibilità (zona rossa), necessita attenzione. ### 12.4 Best Practice per il Rilevamento Duplicati - Inizia con **parametri di default** (k=25, window=4, threshold=5%). - Se ottieni troppi falsi positivi, **aumenta k** o **diminuisci threshold**. - Se sospetti che i duplicati vengano persi, **diminuisci k** o **aumenta threshold**. - **Rivedi sempre manualmente i duplicati fuzzy**—non tutte le similarità sono negative (es. implementazioni di interfacce). --- ## 13. Risoluzione Problemi e FAQ **D: Il rilevamento duplicati è lento su grandi codebase.** **R:** - Usa i filtri del profilo per limitare i tipi di file analizzati. - Aumenta `k` e `window` per ridurre il numero di impronte elaborate. - Escludi file auto-generati di grandi dimensioni o fixture di test. **D: Perché alcuni file mancano di metriche a livello di funzione?** **R:** - L'analisi a livello di funzione richiede `lizard`. Installalo: `pip install lizard`. - Alcuni linguaggi potrebbero non essere completamente supportati da `lizard`. **D: Differ mostra file come "Modified" ma non li ho modificati.** **R:** - Controlla se le terminazioni di riga sono cambiate (CRLF ↔ LF). - Verifica che il file non sia stato riformattato da un auto-formatter. - PyUCC usa hashing del contenuto—qualsiasi modifica a livello di byte attiva lo stato "Modified". **D: Come resetto tutte le baseline?** **R:** - Le baseline sono memorizzate nella cartella `baseline/` (default). - Elimina la cartella baseline o specifiche sottocartelle baseline per resettare. **D: Posso eseguire PyUCC in pipeline CI/CD?** **R:** - Sì! Usa la modalità CLI: ```bash python -m pyucc differ create /path/to/repo python -m pyucc differ diff /path/to/repo python -m pyucc duplicates /path/to/repo --threshold 5.0 ``` - Analizza l'output JSON o i report testuali nei tuoi script di pipeline. ---