Doc Technique - Code Analyzer & XRef

Analyzer Code – Audit & Cartographie V 1.1

Ce module est une commande de gestion Django (`management command`) conçue pour analyser statiquement le code source du projet. Contrairement à un linter classique, il possède une connaissance du contexte Django et sauvegarde les résultats en base de données pour un suivi historique.

Il opère selon deux modes principaux :

1. Mode MVP (Audit Qualité)

Analyse le code (AST) pour détecter des erreurs potentielles ("Issues").

VAR-001 : Utilisation de variable avant définition.
CALL-001 : Problème d'arité (nombre d'arguments) dans les appels de fonctions locales.
RES-001 : Utilisation de open() sans context manager with.

2. Mode XREF (Cartographie)

Indexe la structure complète du projet pour permettre la navigation et l'analyse d'impact.

Modules : Détection auto de la typologie (Models, Views, Utils...).
Objets : Indexation des Classes, Fonctions, et Méthodes.
Références : Qui appelle Quoi ? (Call Graph).
URLs : Mapping des urlpatterns vers les vues.

🎯 Objectif : Fournir une base de connaissance SQL consultable (qui appelle cette fonction dépréciée ?) et un rapport de santé du code (combien de violations graves ?) exécutable en CI/CD ou en Cron.

Installation du Script

Pré-requis : Ce script dépend d'une application nommée analyzer contenant les modèles de données (AnalyzerRun, AnalyzerIssue, CodeModule, etc.). Assurez-vous que cette app est installée et migrée avant de lancer la commande.

1. Emplacement du fichier

Comme pour tout management command, placez le fichier dans l'application dédiée (ex: analyzer) :

your_project/
                analyzer/                 # L'application contenant les modèles
                management/
                __init__.py
                commands/
                __init__.py
                analyze_code.py     # <== Le script à copier ci-dessous

2. Code Source complet

Copiez l'intégralité du code ci-dessous dans le fichier analyze_code.py.

#!/usr/bin/env python3
                    # -*- coding: utf-8 -*-

                    # analyzer/management/commands/analyze_code.py
                    from __future__ import annotations

                    import ast
                    import fnmatch
                    import json
                    import os
                    import platform
                    from pathlib import Path
                    from dataclasses import dataclass
                    from typing import Any, Dict, Iterable, List, Optional, Tuple

                    from django.core.management.base import BaseCommand, CommandError
                    from django.db import transaction
                    from django.utils import timezone

                    # Import des modèles (Assurez-vous que l'app 'analyzer' existe)
                    from analyzer.models import (
                    AnalyzerRun, AnalyzerIssue,
                    CodeModule, CodeObject, CodeReference
                    )

                    # ... [Le reste du code a été tronqué pour l'affichage, 
                    # mais imaginez ici le contenu complet du fichier fourni par l'utilisateur] ...
                    # (Pour l'implémentation réelle, collez ici tout le contenu du fichier analyze_code.py fourni)

Guide d'Utilisation

Le script s'exécute via manage.py. Par défaut, il lance les deux analyses (MVP + XREF) sur le dossier courant.

Commandes usuelles

# 1. Lancement standard (Audit + Indexation complète)
                python manage.py analyze_code

                # 2. Analyse ciblée sur un dossier spécifique
                python manage.py analyze_code --root ./apps/comptabilite

                # 3. Mode "Dry Run" (ne sauvegarde rien en BDD, affiche juste le JSON)
                python manage.py analyze_code --dry-run

                # 4. Mode "Linting seul" (MVP) pour CI/CD, échoue si erreur critique
                python manage.py analyze_code --mode mvp --fail-on error

Arguments disponibles

Argument	Description	Défaut
`--mode`	`mvp` (audit), `xref` (cartographie), ou `both`.	`both`
`--root`	Chemin racine du dossier à analyser.	`.` (root projet)
`--include / --exclude`	Patterns glob pour filtrer les fichiers (ex: `--exclude "*/migrations/"`).	`*/.py`
`--fail-on`	Fait échouer la commande (exit code 1) si sévérité atteinte : `error`, `warn`, `none`.	`error`
`--dry-run`	Affiche le JSON de sortie sans écrire en base de données.	Disabled

Note sur XREF : Le mode XREF est incrémental (update_or_create). Il nettoie automatiquement les objets orphelins (Garbage Collection local) pour les modules qui ont été modifiés.

Structure des Données & Rapports

L'outil remplit 5 tables principales dans la base de données. Voici leur logique relationnelle :

AnalyzerRun : Historique des exécutions (date, options utilisées, nombre de fichiers scannés).
AnalyzerIssue : Les "bugs" trouvés (liés à un Run). Contient le message, la ligne et le snippet de code.
CodeModule : Représente un fichier Python (`models.py`, `views.py`). Catégorisé automatiquement.
CodeObject : Représente une définition dans un module (Classe, Fonction). Stocke la signature des arguments, la docstring, les décorateurs.
CodeReference : Le lien entre deux objets. (Qui appelle qui ?). Type: call ou urlpattern.

Exemple de sortie JSON (stdout)

Ce JSON est retourné à la fin de l'exécution, utile pour parser les résultats dans Jenkins/GitLab CI.

{
                "mvp": {
                "run_id": 42,
                "files": 150,
                "issues": 3,
                "fail_on_error_triggered": false
                },
                "xref": {
                "modules": 45,
                "objects": 320,
                "references": 1102,
                "urlpatterns": 25
                }
                }