SXXXXXXX_PyUCC/README.md

PyUCC - Python Unified Code Counter

PyUCC is a robust, Python-based static analysis tool designed to count SLOC (Source Lines of Code), calculate complexity metrics, and track code evolution through advanced baseline comparison.

Built with strict engineering principles (PEP8, Separation of Concerns), PyUCC offers a responsive GUI to help developers and managers maintain code quality over time.

---

🇬🇧 English Documentation

Key Features

• 🔍 Multi-Language Scanning: Automatically detects and scans source files for C++, Python, Java, JavaScript, and many other languages.
• 🔢 SLOC Counting: Detailed breakdown of Physical lines, Code lines, Comments, and Blank lines.
• 📊 Advanced Metrics:
  • Cyclomatic Complexity (CC): Identify complex and error-prone logic.
  • Maintainability Index (MI): quantitative score of how maintainable the code is.
• 🔀 Differing & Baselines:
  • Create snapshots (Baselines) of your project.
  • Compare current code against previous baselines using smart matching algorithms (Gale-Shapley + Levenshtein).
  • Visualize Added, Deleted, and Modified files with delta metrics.
• 👁️ Visual Diff Viewer: Integrated side-by-side viewer with syntax highlighting and minimap to inspect changes.
• ⚙️ Custom Profiles: Save configurations for different projects (filters, ignore patterns, languages).

Installation

PyUCC requires Python 3.8+.

1. Clone the repository:

   git clone https://github.com/yourusername/pyucc.git
   cd pyucc
   

2. Install dependencies:

   pip install -r requirements.txt
   

Usage

Launch the GUI: Run the module from the repository root:

python -m pyucc

First Steps:

1. Click Manage to create a new Profile (select your source folder and languages).
2. Click Scan to verify file detection.
3. Click Differing to create your first Baseline.

Documentation

For a deep dive into usage, workflows, and configuration, please refer to the User Manual:

👉 English Manual

👉 Manuale Italiano

What's New (Highlights)

This release adds new capabilities to improve duplicate detection and make baseline reports more reproducible:

• Duplicate Detection: Exact and fuzzy duplicate finding (GUI button + CLI). Exports to CSV and textual UCC-style report.
• UCC-style reports: Compact table with additional delta columns (ΔCode, ΔComm, ΔBlank, ΔFunc, ΔAvgCC, ΔMI) for quick numeric comparison.
• Scanner & Baseline Improvements: Centralized scanner, ignore-pattern normalization (e.g., .bak -> *.bak, case-insensitive), and baseline parameter storage for reproducibility.

See the manuals for full usage examples and a worked example demonstrating baseline -> duplicates -> export.

Technical Philosophy

• Separation of Concerns: Core logic is strictly separated from the GUI layer.
• Non-Blocking UI: Heavy tasks run in background threads using a custom WorkerManager.
• Clean Code: Strictly adheres to PEP8 standards.

---

🇮🇹 Documentazione in Italiano

Panoramica

PyUCC è uno strumento di analisi statica scritto in Python, progettato per contare le righe di codice (SLOC), calcolare metriche di complessità e tracciare l'evoluzione del software tramite il confronto tra versioni (Baseline).

Sviluppato seguendo rigorosi principi di ingegneria del software, PyUCC offre un'interfaccia grafica reattiva per aiutare sviluppatori e manager a mantenere alta la qualità del codice.

Funzionalità Principali

• 🔍 Scansione Multi-Linguaggio: Rileva e scansiona automaticamente C++, Python, Java, JavaScript e molti altri.
• 🔢 Conteggio SLOC: Dettaglio di righe Fisiche, Codice effettivo, Commenti e Righe vuote.
• 📊 Metriche Avanzate:
  • Complessità Ciclomatica (CC): Identifica la logica complessa e soggetta a errori.
  • Maintainability Index (MI): Punteggio quantitativo sulla manutenibilità del codice.
• 🔀 Differing e Baseline:
  • Crea istantanee (Baseline) del tuo progetto.
  • Confronta il codice attuale con le baseline precedenti usando algoritmi di matching intelligenti.
  • Visualizza file Aggiunti, Rimossi e Modificati con i delta delle metriche.
• 👁️ Visual Diff Viewer: Visualizzatore integrato fianco a fianco con evidenziazione sintassi e minimappa per ispezionare le modifiche.
• ⚙️ Profili Personalizzati: Salva configurazioni per progetti diversi (filtri, pattern di esclusione, linguaggi).

Installazione

PyUCC richiede Python 3.8+.

1. Clona il repository:

   git clone https://github.com/tuousername/pyucc.git
   cd pyucc
   

2. Installa le dipendenze:

   pip install -r requirements.txt
   

Utilizzo

Avviare l'interfaccia grafica: Esegui il modulo dalla root del repository:

python -m pyucc

Primi Passi:

1. Clicca su Manage per creare un nuovo Profilo (seleziona la cartella sorgente e i linguaggi).
2. Clicca su Scan per verificare che i file vengano rilevati.
3. Clicca su Differing per creare la tua prima Baseline.

Documentazione

Per una guida approfondita sull'utilizzo, i flussi di lavoro e la configurazione, consulta il Manuale Utente:

👉 Leggi il Manuale Utente

Filosofia Tecnica

• Separazione delle Responsabilità: La logica Core è separata dallo strato GUI.
• UI Non Bloccante: Le operazioni pesanti girano in thread separati grazie a un WorkerManager dedicato.
• Clean Code: Il codice rispetta rigorosamente gli standard PEP8.

---

2025 - Developed with Python.