# 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 Primo Avvio e 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.2 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.3 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. --- Se vuoi, posso aggiungere un esempio passo-passo che mostra come creare una baseline, eseguire la ricerca duplicati e esportare CSV + report UCC sia da GUI che da CLI. Vuoi che lo prepari con comandi e file di esempio?