repository: aggiunta di documentazione base

docs/development/coding-standards.md

@@ -0,0 +1,514 @@
+# SMAVS Coding Standards
+
+**Version:** 1.0.0
+**Status:** Approved
+**Project:** Spiral – SMAVS Composition Engine
+
+---
+
+# 1. Scopo
+
+Questo documento definisce gli standard ufficiali di sviluppo del framework **SMAVS (Su Misura Al Vostro Sistema)**.
+
+Ogni file del progetto deve rispettare le regole qui descritte.
+
+L'obiettivo è garantire:
+
+- uniformità del codice;
+- elevata leggibilità;
+- semplicità di manutenzione;
+- coerenza architetturale;
+- qualità costante durante l'intero ciclo di vita del framework.
+
+Le presenti regole costituiscono lo standard ufficiale di sviluppo del progetto.
+
+---
+
+# 2. Principi Fondamentali
+
+Il codice deve sempre rispettare i seguenti principi.
+
+## Leggibilità
+
+Il codice viene letto molte più volte di quante venga scritto.
+
+La leggibilità ha sempre priorità rispetto alla brevità.
+
+---
+
+## Esplicitezza
+
+L'esplicito è sempre preferibile all'implicito.
+
+Il comportamento del codice deve risultare evidente senza richiedere interpretazioni.
+
+---
+
+## Determinismo
+
+Ogni componente deve produrre sempre lo stesso risultato a parità di input.
+
+---
+
+## Immutabilità
+
+I modelli del dominio sono immutabili.
+
+---
+
+## Single Responsibility
+
+Ogni classe possiede una singola responsabilità.
+
+---
+
+## Composition over Inheritance
+
+La composizione è sempre preferibile all'ereditarietà.
+
+---
+
+## Dependency Inversion
+
+Le dipendenze devono sempre puntare verso le astrazioni.
+
+---
+
+## Testabilità
+
+Ogni componente deve poter essere testato in isolamento.
+
+---
+
+# 3. Convenzioni Generali
+
+## Versione Python
+
+Python 3.11+
+
+---
+
+## Formatter
+
+Ruff Format
+
+---
+
+## Linter
+
+Ruff
+
+---
+
+## Type Checker
+
+MyPy
+
+---
+
+## Testing
+
+Pytest
+
+---
+
+## Coverage
+
+Coverage minimo:
+
+95%
+
+---
+
+# 4. Convenzioni di Naming
+
+## Package
+
+snake_case
+
+```
+shared
+value_objects
+analysis
+composition
+```
+
+---
+
+## Moduli
+
+snake_case
+
+```
+identifier.py
+module_registry.py
+composition_context.py
+```
+
+---
+
+## Classi
+
+PascalCase
+
+```
+Identifier
+CompositionContext
+ModuleRegistry
+```
+
+---
+
+## Funzioni
+
+snake_case
+
+```
+build_context()
+resolve_modules()
+```
+
+---
+
+## Variabili
+
+snake_case
+
+```
+execution_plan
+module_registry
+```
+
+---
+
+## Costanti
+
+UPPER_CASE
+
+```
+DEFAULT_PRIORITY
+MAX_DEPTH
+```
+
+---
+
+## Membri privati
+
+Singolo underscore
+
+```
+_identifier
+_registry
+```
+
+---
+
+# 5. Organizzazione della Repository
+
+Ogni package deve contenere esclusivamente componenti appartenenti alla propria responsabilità.
+
+Non sono consentite dipendenze circolari.
+
+---
+
+# 6. Organizzazione dei File
+
+Ogni file Python deve seguire rigorosamente il seguente ordine.
+
+```
+Module Docstring
+
+↓
+
+Future Imports
+
+↓
+
+Standard Library
+
+↓
+
+Third Party Imports
+
+↓
+
+Project Imports
+
+↓
+
+__all__
+
+↓
+
+Constants
+
+↓
+
+Classi
+
+↓
+
+Funzioni
+```
+
+---
+
+# 7. Organizzazione degli Import
+
+Gli import devono essere ordinati nel seguente modo.
+
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pathlib import Path
+
+from typing import Final
+
+from smavs.shared...
+```
+
+Non sono consentiti import inutilizzati.
+
+Non sono consentiti wildcard import.
+
+```
+from package import *
+```
+
+---
+
+# 8. Docstring
+
+Ogni modulo pubblico deve possedere una docstring.
+
+Ogni classe pubblica deve possedere una docstring.
+
+Ogni metodo pubblico deve possedere una docstring quando il comportamento non è immediatamente evidente.
+
+Lo stile adottato è **Google Style**.
+
+---
+
+# 9. Type Hinting
+
+Tutte le funzioni devono utilizzare typing completo.
+
+Consentito
+
+```python
+def build(name: str) -> Identifier:
+```
+
+Non consentito
+
+```python
+def build(name):
+```
+
+---
+
+Mai utilizzare
+
+```
+list
+dict
+tuple
+set
+```
+
+Utilizzare sempre
+
+```
+list[str]
+dict[str, str]
+tuple[int, ...]
+set[str]
+```
+
+---
+
+# 10. Dataclass
+
+Tutti i Value Object devono essere dichiarati nel seguente modo.
+
+```python
+@dataclass(
+    frozen=True,
+    slots=True,
+)
+```
+
+Le dataclass mutabili non sono consentite nel dominio.
+
+---
+
+# 11. Protocol
+
+Le interfacce del Core devono essere implementate tramite Protocol.
+
+Non utilizzare classi astratte salvo casi eccezionali.
+
+---
+
+# 12. Value Object
+
+I Value Object devono:
+
+- essere immutabili;
+- essere hashable;
+- essere confrontabili;
+- non possedere identità.
+
+---
+
+# 13. Entity
+
+Le Entity devono:
+
+- possedere un Identifier;
+- mantenere la propria identità;
+- incapsulare il proprio stato.
+
+---
+
+# 14. Aggregate Root
+
+Ogni Aggregate Root è responsabile della consistenza del proprio Aggregate.
+
+Le modifiche interne devono essere sempre controllate dall'Aggregate Root.
+
+---
+
+# 15. Domain Events
+
+I Domain Event rappresentano fatti già accaduti.
+
+Sono immutabili.
+
+---
+
+# 16. Exceptions
+
+È vietato utilizzare
+
+```python
+raise Exception(...)
+```
+
+Ogni errore deve derivare da:
+
+```
+SMAVSError
+```
+
+---
+
+# 17. Logging
+
+Utilizzare esclusivamente logging strutturato.
+
+Non utilizzare print().
+
+---
+
+# 18. Testing
+
+Ogni componente deve possedere test unitari.
+
+La struttura deve seguire il pattern:
+
+```
+Arrange
+
+Act
+
+Assert
+```
+
+---
+
+Ogni test deve verificare un solo comportamento.
+
+---
+
+# 19. Commenti
+
+I commenti devono spiegare il perché.
+
+Mai spiegare il cosa.
+
+---
+
+# 20. Refactoring
+
+Prima di effettuare un refactoring verificare:
+
+- retrocompatibilità;
+- copertura dei test;
+- conformità alla SAS.
+
+---
+
+# 21. Checklist prima del Commit
+
+Verificare sempre:
+
+- Ruff
+- MyPy
+- Pytest
+- Coverage
+- Pre-Commit
+
+Tutti i controlli devono risultare verdi.
+
+---
+
+# 22. Checklist prima della Pull Request
+
+La Pull Request deve:
+
+- compilare correttamente;
+- superare la CI;
+- mantenere il coverage;
+- rispettare la SAS;
+- rispettare la Roadmap.
+
+---
+
+# 23. Regole Fondamentali
+
+Le seguenti regole sono considerate invarianti del progetto.
+
+1. Il codice deve essere leggibile prima di essere intelligente.
+
+2. L'esplicito è preferibile all'implicito.
+
+3. Ogni classe possiede una sola responsabilità.
+
+4. Il dominio non conosce l'infrastruttura.
+
+5. Nessuna dipendenza circolare.
+
+6. Nessun TODO nel codice.
+
+7. Nessun codice morto.
+
+8. Nessun wildcard import.
+
+9. Nessuna eccezione generica.
+
+10. Ogni nuova funzionalità deve essere testabile.
+
+11. Ogni modifica deve rispettare la Software Architecture Specification.
+
+12. Ogni implementazione deve seguire rigorosamente l'Implementation Roadmap.
+
+---
+
+# 24. Stato della Specifica
+
+Questo documento costituisce lo standard ufficiale di sviluppo del framework SMAVS.
+
+Ogni nuovo contributo al progetto deve rispettare integralmente le regole qui definite.