# SMAVS Development Environment

**Version:** 1.0.0
**Status:** Approved
**Project:** Spiral – SMAVS Composition Engine

---

# 1. Scopo

Questo documento definisce l'ambiente di sviluppo ufficiale del framework **SMAVS (Su Misura Al Vostro Sistema)**.

L'obiettivo è garantire che tutti gli sviluppatori utilizzino un ambiente coerente, riproducibile e conforme agli standard del progetto.

---

# 2. Requisiti di Sistema

## Sistema Operativo

Sistemi supportati:

- Windows 11
- Linux
- macOS

---

## Python

Versione minima supportata

```
Python 3.11
```

Versioni consigliate

```
Python 3.11.x
Python 3.12.x
```

---

## Git

Versione minima

```
Git 2.40+
```

---

# 3. Repository

Clonare il repository ufficiale.

```bash
git clone https://gitea.netbird.smavs.duckdns.org/SMAVS/smavs.git
```

Entrare nella directory.

```bash
cd smavs
```

---

# 4. Ambiente Virtuale

Ogni sviluppo deve essere effettuato all'interno di un ambiente virtuale dedicato.

Creazione

```bash
python -m venv .venv
```

---

## Windows

```powershell
.\.venv\Scripts\Activate.ps1
```

---

## Linux

```bash
source .venv/bin/activate
```

---

## macOS

```bash
source .venv/bin/activate
```

---

# 5. Installazione Dipendenze

Installazione del progetto in modalità editable.

```bash
python -m pip install -e ".[dev]"
```

Le dipendenze di sviluppo comprendono:

- Ruff
- MyPy
- Pytest
- Coverage
- MkDocs
- MkDocs Material
- Pre-Commit

---

# 6. Configurazione Git

Configurare il proprio utente Git.

```bash
git config --global user.name "<Nome>"
git config --global user.email "<Email>"
```

Impostare il branch predefinito.

```bash
git config --global init.defaultBranch main
```

---

# 7. Pre-Commit

Installazione degli hook.

```bash
python -m pre_commit install
```

Verifica manuale.

```bash
python -m pre_commit run --all-files
```

Tutti gli hook devono risultare verdi prima di ogni commit.

---

# 8. Ruff

Verifica del codice.

```bash
python -m ruff check .
```

Correzione automatica.

```bash
python -m ruff check . --fix
```

Formatter.

```bash
python -m ruff format .
```

Verifica formatter.

```bash
python -m ruff format --check .
```

---

# 9. MyPy

Verifica del typing.

```bash
python -m mypy .
```

---

# 10. Pytest

Esecuzione dei test.

```bash
python -m pytest
```

---

# 11. Coverage

Esecuzione della coverage.

```bash
python -m coverage run -m pytest
python -m coverage report
```

Generazione del report HTML.

```bash
python -m coverage html
```

---

# 12. MkDocs

Avvio del server locale.

```bash
mkdocs serve
```

Generazione della documentazione.

```bash
mkdocs build
```

---

# 13. Workflow Quotidiano

Ogni attività di sviluppo deve seguire il seguente flusso.

```
git pull

↓

Sviluppo

↓

git status

↓

git add .

↓

python -m pre_commit run --all-files

↓

git commit

↓

git push
```

---

# 14. Continuous Integration

Ogni push attiva automaticamente la pipeline CI.

La pipeline verifica:

- Ruff
- MyPy
- Pytest
- Coverage

Il branch `main` deve rimanere sempre stabile.

---

# 15. Visual Studio Code

Estensioni consigliate.

- Python
- Pylance
- Ruff
- EditorConfig
- GitLens
- Markdown All in One

---

Impostazioni consigliate.

```json
{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.ruff": "explicit",
        "source.organizeImports.ruff": "explicit"
    },
    "files.eol": "\n",
    "files.insertFinalNewline": true,
    "files.trimTrailingWhitespace": true,
    "python.analysis.typeCheckingMode": "strict"
}
```

---

# 16. Directory Generate Automaticamente

Le seguenti directory non devono essere versionate.

```
.venv/
__pycache__/
.pytest_cache/
.ruff_cache/
.mypy_cache/
htmlcov/
site/
```

---

# 17. Aggiornamento Dipendenze

Aggiornare periodicamente le dipendenze.

```bash
python -m pip install --upgrade pip

python -m pip install -e ".[dev]"
```

---

# 18. Risoluzione Problemi

Ricreare completamente l'ambiente virtuale.

Windows

```powershell
Remove-Item -Recurse -Force .venv
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
```

Linux / macOS

```bash
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
```

---

# 19. Regole Fondamentali

1. Utilizzare sempre un ambiente virtuale dedicato.

2. Installare sempre le dipendenze tramite il gruppo `dev`.

3. Utilizzare sempre `python -m` per eseguire gli strumenti.

4. Eseguire sempre `pre-commit` prima di ogni commit.

5. Non effettuare push con hook non superati.

6. Non modificare manualmente la configurazione degli strumenti senza approvazione.

7. Mantenere sincronizzato l'ambiente locale con il repository.

---

# 20. Stato della Specifica

Questo documento costituisce la specifica ufficiale dell'ambiente di sviluppo del framework SMAVS.

Ogni ambiente di sviluppo deve essere configurato secondo le regole qui definite.