Code/docs/GUIDE_RUFF.md

# Guide d'utilisation de Ruff

## Configuration effectuee

J'ai configure Ruff pour votre projet FabNum avec deux fichiers :

### 1. pyproject.toml
Configuration principale de Ruff avec :
- **Longueur de ligne** : 120 caractères maximum
- **Exclusions** : pgpt/, IA/, batch_ia/ (modules priorite basse)
- **Regles activees** :
  - Erreurs de style (pycodestyle)
  - Detection de bugs (pyflakes, bugbear)
  - **Docstrings obligatoires** (pydocstyle)
  - Tri automatique des imports (isort)
  - Simplifications de code
  - Detection de code mort

### 2. .vscode/settings.json
Configuration VSCodium pour :
- Formattage automatique avec Ruff
- Organisation des imports au save
- Detection des problemes en temps reel
- Integration avec pytest

## Utilisation dans VSCodium

### Actions automatiques
Lorsque vous ouvrez un fichier Python, Ruff va :
- Souligner en rouge/jaune les problemes detectes
- Proposer des corrections rapides (Quick Fix)
- Organiser les imports quand vous sauvegardez

### Actions manuelles

**Voir tous les problemes** :
- Panneau "Problemes" (Ctrl+Shift+M)
- Filtre par fichier, par type (erreur/warning)

**Corriger automatiquement** :
1. Clic droit sur le code souligne
2. "Quick Fix..." (Ctrl+.)
3. Selectionner "Ruff: Fix all auto-fixable problems"

**Organiser les imports** :
- Clic droit > "Organiser les imports"
- Ou sauvegarde automatique (deja configure)

**Formater un fichier** :
- Clic droit > "Formater le document"
- Ou Shift+Alt+F

## Regles principales pour les docstrings

Ruff va exiger des docstrings au format Google :

### Fonction simple
```python
def calculer_ivc(graph, node):
    """Calcule l'indice de vulnerabilite competitive pour un noeud.

    Args:
        graph: Le graphe NetworkX contenant les donnees.
        node: L'identifiant du noeud a analyser.

    Returns:
        float: La valeur IVC calculee.

    Raises:
        ValueError: Si le noeud n'existe pas dans le graphe.
    """
    # code...
```

### Fonction complexe avec exemples
```python
def synchroniser_gitea(repo_name, force=False):
    """Synchronise les donnees locales avec le depot Gitea.

    Cette fonction compare les timestamps locaux et distants pour determiner
    si une synchronisation est necessaire. En mode force, ignore le cache.

    Args:
        repo_name: Nom du depot Gitea (DEPOT_FICHES ou DEPOT_CODE).
        force: Si True, force la synchronisation meme si le cache est valide.

    Returns:
        dict: Dictionnaire avec les cles :
            - 'synced': bool, True si synchronisation effectuee
            - 'files_updated': int, nombre de fichiers mis a jour
            - 'timestamp': str, horodatage de la synchronisation

    Raises:
        ConnectionError: Si impossible de contacter le serveur Gitea.
        ValueError: Si repo_name n'est pas reconnu.

    Example:
        >>> result = synchroniser_gitea('DEPOT_FICHES', force=True)
        >>> print(result['files_updated'])
        12
    """
    # code...
```

### Classe
```python
class GraphAnalyzer:
    """Analyseur de graphes pour les chaines d'approvisionnement.

    Cette classe fournit des methodes pour analyser les dependances
    et calculer les indices de risque sur un graphe NetworkX.

    Attributes:
        graph: Le graphe NetworkX a analyser.
        config: Configuration des seuils et parametres.
    """

    def __init__(self, graph, config=None):
        """Initialise l'analyseur avec un graphe.

        Args:
            graph: Graphe NetworkX des dependances.
            config: Configuration optionnelle (dict).
        """
        # code...
```

## Ce que Ruff va detecter

### Problemes de docstrings
- Fonctions publiques sans docstring
- Docstrings mal formatees
- Arguments non documentes
- Valeurs de retour non documentees

### Problemes de code
- Imports non utilises
- Variables definies mais jamais utilisees
- Code mort (apres return/break)
- Comparaisons dangereuses (== None au lieu de is None)
- Lignes trop longues (>120 caracteres)
- Complexite trop elevee

### Suggestions d'amelioration
- Utiliser pathlib au lieu de os.path
- Simplifier les comprehensions
- Utiliser f-strings au lieu de .format()
- Remplacer list() + comprehension par comprehension directe

## Commandes utiles (si Ruff CLI installe)

Si vous souhaitez installer Ruff en ligne de commande :

```bash
pip install ruff

# Verifier tout le projet
ruff check app/ utils/

# Corriger automatiquement ce qui peut l'etre
ruff check app/ utils/ --fix

# Voir les statistiques
ruff check app/ utils/ --statistics

# Formater le code
ruff format app/ utils/
```

## Prochaines etapes

1. **Rechargez VSCodium** pour que la configuration prenne effet
2. **Ouvrez un fichier Python** (ex: app/fiches/interface.py)
3. **Regardez le panneau Problemes** (Ctrl+Shift+M)
4. Vous verrez la liste des problemes detectes par Ruff

Ruff va vous guider pour :
- Ajouter les docstrings manquantes
- Corriger les problemes de style
- Ameliorer la qualite du code

## Questions frequentes

**Q: Trop de problemes affiches, c'est normal ?**
R: Oui, la premiere fois Ruff peut detecter beaucoup de choses. Traitez-les progressivement, module par module.

**Q: Puis-je desactiver certaines regles ?**
R: Oui, editez pyproject.toml, section [tool.ruff.lint] > ignore.

**Q: Comment ignorer un warning sur une ligne specifique ?**
R: Ajoutez un commentaire : `# noqa: CODE` (ex: `# noqa: D103` pour ignorer docstring manquante)

**Q: formatOnSave est a false, pourquoi ?**
R: Pour eviter de reformater tout le code d'un coup. Vous pouvez le mettre a true quand vous serez pret.

## Fichiers de configuration

- **pyproject.toml** : Configuration Ruff (regles, exclusions, style)
- **.vscode/settings.json** : Integration VSCodium
- **requirements.txt** : Dependances Python (existe deja)

## Support

Pour plus d'informations : https://docs.astral.sh/ruff/