diff --git a/doc/English-manual.md b/doc/English-manual.md index f3cc1d3..f0fc61a 100644 --- a/doc/English-manual.md +++ b/doc/English-manual.md @@ -53,9 +53,82 @@ The interface is divided into functional zones to keep the workflow organized. --- -## 4. Step-by-Step Guide +## 4. Configuration and Settings -### 4.1 First Run & Profile Configuration +### 4.1 Configuration Files Location + +PyUCC stores all configuration in the application directory (where the executable or source code is located): + +- **`profiles.json`** - Stores all your analysis profiles (project paths, filters, ignore patterns) +- **`settings.json`** - Stores application settings (baseline directory, retention policy, duplicates parameters) + +**Location:** +- If running from source: in the repository root folder (e.g., `C:\src\PyUcc\`) +- If running from compiled exe: in the same folder as the executable + +**Advantages:** +- Fully portable application - copy the entire folder to move your setup +- Easy to backup - just backup the application folder +- No hidden files in user's home directory + +### 4.2 Application Settings (Settings.json) + +You can configure PyUCC's behavior through the **⚙️ Settings** menu in the top bar. + +**Available Settings:** + +1. **Baseline Directory** + - **What it is:** Where PyUCC stores baseline snapshots. + - **Default:** `baseline/` subfolder in the application directory. + - **Recommendation:** Use the default, or set a custom path if you want to store baselines on a network drive or separate disk. + - **Example:** `D:\ProjectBaselines\` or `\\server\share\baselines\` + +2. **Max Baselines to Keep** + - **What it is:** Maximum number of baseline snapshots to retain per profile. + - **Default:** 5 + - **Behavior:** When exceeded, PyUCC automatically deletes the oldest baselines. + - **Recommendation:** + - 3-5 for small projects + - 10+ for critical projects requiring long history + - 20+ if disk space is not a concern + +3. **Zip Baselines** + - **What it is:** Whether to compress baseline snapshots as `.zip` files. + - **Default:** `false` (disabled) + - **Advantages when enabled:** + - Saves disk space (50-80% reduction for source code) + - Faster to transfer/backup + - **Disadvantages:** + - Slightly slower to create/compare (compression overhead) + - Cannot browse snapshot files directly + - **Recommendation:** Enable for large projects (>10,000 files) or when disk space is limited. + +4. **Duplicates Settings** (stored automatically) + - Threshold, k-gram size, winnowing window + - These are saved when you use the Duplicates feature + - See Section 9 for detailed explanation + +**How to Configure:** + +1. Click **⚙️ Settings** in the top bar. +2. Set your preferred baseline directory (or leave default). +3. Set max baselines to keep. +4. Check "Zip baselines" if desired. +5. Click **Save**. + +**First-Time Setup Recommendation:** + +At first run, PyUCC will use sensible defaults: +- Baselines stored in `baseline/` subfolder +- Keep last 5 baselines +- No compression + +**You should configure Settings if:** +- You want baselines on a different drive (e.g., network storage, external disk) +- You need to keep more baseline history +- You're running out of disk space and want compression + +### 4.3 First Run & Profile Configuration The first thing to do upon opening PyUCC is to define *what* to analyze. 1. Click on **⚙️ Manage...** in the top bar. @@ -66,7 +139,7 @@ The first thing to do upon opening PyUCC is to define *what* to analyze. 6. In the **Ignore patterns** box, you can keep the defaults (which already exclude `.git`, `__pycache__`, etc.). 7. Click **💾 Save**. -### 4.2 Simple Analysis (Scan, Countings, Metrics) +### 4.4 Simple Analysis (Scan, Countings, Metrics) If you only want to analyze the current state without comparisons: * **🔍 Scan:** Simply verifies which files are found based on the profile filters. Useful to check if you are including the right files. @@ -75,7 +148,7 @@ If you only want to analyze the current state without comparisons: > **Tip:** You can double-click on a file in the results table to open it in the built-in **File Viewer**, which provides syntax highlighting and a colored minimap (blue=code, green=comments). -### 4.3 The "Differing" Workflow (Comparison) +### 4.5 The "Differing" Workflow (Comparison) This is PyUCC's most powerful feature. **Step A: Create the First Baseline** diff --git a/doc/Italian-manual.md b/doc/Italian-manual.md index 33a201d..6d5527b 100644 --- a/doc/Italian-manual.md +++ b/doc/Italian-manual.md @@ -55,7 +55,67 @@ L'interfaccia è divisa in zone funzionali per mantenere il flusso di lavoro ord ## 4. Guida Passo-Passo -### 4.1 Primo Avvio e Configurazione Profilo +### 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. @@ -66,7 +126,7 @@ Non appena apri PyUCC, la prima cosa da fare è dire al programma *cosa* analizz 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) +### 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. @@ -75,7 +135,7 @@ Se vuoi solo analizzare lo stato attuale senza confronti: > **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) +### 4.5 Il Flusso di Lavoro "Differing" (Confronto) Questa è la funzione più potente di PyUCC. **Passo A: Creare la prima Baseline** diff --git a/doc/PyUCC_SUM_20251212.pdf b/doc/PyUCC_SUM_20251212.pdf new file mode 100644 index 0000000..83d93c1 Binary files /dev/null and b/doc/PyUCC_SUM_20251212.pdf differ diff --git a/doc/PyUCC_SUM_20251212_ENG.pdf b/doc/PyUCC_SUM_20251212_ENG.pdf new file mode 100644 index 0000000..5f51557 Binary files /dev/null and b/doc/PyUCC_SUM_20251212_ENG.pdf differ diff --git a/doc/PyUCC_SUM_20251212_ITA.pdf b/doc/PyUCC_SUM_20251212_ITA.pdf new file mode 100644 index 0000000..38b25c1 Binary files /dev/null and b/doc/PyUCC_SUM_20251212_ITA.pdf differ diff --git a/doc/_SUM_20251212.pdf b/doc/_SUM_20251212.pdf new file mode 100644 index 0000000..e73b81a Binary files /dev/null and b/doc/_SUM_20251212.pdf differ diff --git a/doc/_SUM___20251212.docx b/doc/_SUM___20251212.docx new file mode 100644 index 0000000..99c5522 Binary files /dev/null and b/doc/_SUM___20251212.docx differ diff --git a/doc/_SUM___20251212.pdf b/doc/_SUM___20251212.pdf new file mode 100644 index 0000000..060330e Binary files /dev/null and b/doc/_SUM___20251212.pdf differ diff --git a/pyucc/_version.py b/pyucc/_version.py index d3829e9..84ed46b 100644 --- a/pyucc/_version.py +++ b/pyucc/_version.py @@ -6,10 +6,10 @@ import re # --- Version Data (Generated) --- -__version__ = "v.0.0.0.19-0-g79ed9c1-dirty" -GIT_COMMIT_HASH = "79ed9c1d728bb53ace64ca2c232eb3c038b69152" +__version__ = "v.0.0.0.20-0-g9538919-dirty" +GIT_COMMIT_HASH = "95389193747b356fc287b149371c64ad557fcb30" GIT_BRANCH = "master" -BUILD_TIMESTAMP = "2025-12-12T09:07:06.615288+00:00" +BUILD_TIMESTAMP = "2025-12-12T09:15:00.613998+00:00" IS_GIT_REPO = True # --- Default Values (for comparison or fallback) --- diff --git a/todo.md b/todo.md index f9aff28..fb9197c 100644 --- a/todo.md +++ b/todo.md @@ -15,9 +15,9 @@ - [x] poter ordinare la tabella cliccando sulla colonna sia in ordine crescente che descrescente - [ ] aggiungere schermata di debug dove provare le singole funzioni su singolo file. - [x] implementare conteggio esteso stile UCC (Whole/Embedded comments, Directives, Data Decl, Exec Instr, Logical SLOC) - vedi `pyucc/core/ucc_extended_counting.py` -- [ ] integrare conteggio esteso nella GUI principale -- [ ] fare confronto con uscita UCC per quanto riguarda la complessità ciclomatica e fornire un report più approfondito usando gli stessi indicatori numerici e gli stessi indicatore tipo "low, mediuam, high, very high" -- [ ] inserire la ricerca delle funzioni duplicate all'interno del codice. +- [x] integrare conteggio esteso nella GUI principale +- [x] fare confronto con uscita UCC per quanto riguarda la complessità ciclomatica e fornire un report più approfondito usando gli stessi indicatori numerici e gli stessi indicatore tipo "low, mediuam, high, very high" +- [x] inserire la ricerca delle funzioni duplicate all'interno del codice. # FIXME List