Ruff Recursive Fix

Aperçu

Utilisez cette compétence pour appliquer la qualité du code avec Ruff dans un workflow itératif et contrôlé. Elle prend en charge :

• Limitation optionnelle du périmètre à un dossier spécifique.
• Paramètres par défaut du projet depuis pyproject.toml.
• Invocation flexible de Ruff (uv, ruff direct, python -m ruff, ou équivalent).
• Surcharges optionnelles de règles par exécution (--select, --ignore, --extend-select, --extend-ignore).
• Autofixes automatiques sûrs puis non sûrs.
• Révision des diff après chaque passage de correction.
• Répétition récursive jusqu'à résolution des findings ou décision requise.
• Utilisation judicieuse de # noqa inline seulement quand la suppression est justifiée.

Entrées

Rassemblez ces entrées avant d'exécuter :

• target_path (optionnel) : dossier ou fichier à vérifier. Vide signifie tout le repository.
• ruff_runner (optionnel) : préfixe de commande Ruff explicite (par exemple uv run, ruff, python -m ruff, pipx run ruff).
• rules_select (optionnel) : codes de règles séparés par des virgules à appliquer.
• rules_ignore (optionnel) : codes de règles séparés par des virgules à ignorer.
• extend_select (optionnel) : règles supplémentaires à ajouter sans remplacer les défauts configurés.
• extend_ignore (optionnel) : règles supplémentaires à ignorer sans remplacer les défauts configurés.
• allow_unsafe_fixes (défaut : true) : s'il faut exécuter les fixes non sûrs de Ruff.
• ask_on_ambiguity (défaut : true) : toujours demander à l'utilisateur quand plusieurs choix valides existent.

Construction de commandes

Construisez des commandes Ruff à partir des entrées.

0. Résoudre le runner Ruff

Déterminez un préfixe ruff_cmd réutilisable avant de construire les commandes.

Ordre de résolution :

1. Si ruff_runner est fourni, utilisez-le tel quel.
2. Sinon, si uv est disponible et que Ruff est géré via uv, utilisez uv run ruff.
3. Sinon, si ruff est disponible dans PATH, utilisez ruff.
4. Sinon, si Python est disponible et que Ruff est installé dans cet environnement, utilisez python -m ruff.
5. Sinon, utilisez tout équivalent spécifique au projet qui invoque Ruff installé (par exemple pipx run ruff), ou arrêtez et demandez à l'utilisateur.

Utilisez le même ruff_cmd résolu pour toutes les commandes check et format du workflow.

Commande de base :

<ruff_cmd> check

Commande du formateur :

<ruff_cmd> format

Avec cible optionnelle :

<ruff_cmd> format <target_path>

Ajoutez la cible optionnelle :

<ruff_cmd> check <target_path>

Ajoutez les surcharges optionnelles au besoin :

--select <codes>
--ignore <codes>
--extend-select <codes>
--extend-ignore <codes>

Exemples :

# Projet complet avec défauts de pyproject.toml
ruff check

# Un dossier avec défauts
python -m ruff check src/models

# Surcharge pour ignorer les règles docs et TODO-like pour cette exécution
uv run ruff check src --extend-ignore D,TD

# Vérifier seulement les règles sélectionnées dans un dossier
ruff check src/data --select F,E9,I

Workflow

1. Analyse de référence

1. Exécutez <ruff_cmd> check avec le périmètre et les options sélectionnés.
2. Classifiez les findings par type :
   • Autofixable sûr.
   • Autofixable non sûr.
   • Non autofixable.
3. S'il ne reste aucun finding, arrêtez.

2. Passage d'autofix sûr

1. Exécutez Ruff avec --fix en utilisant le même périmètre/options.
2. Révisez le diff résultant attentivement pour la correction sémantique et la cohérence de style.
3. Exécutez <ruff_cmd> format sur le même périmètre.
4. Réexécutez <ruff_cmd> check pour actualiser les findings restants.

3. Passage d'autofix non sûr

Exécutez seulement si des findings restent et allow_unsafe_fixes=true.

1. Exécutez Ruff avec --fix --unsafe-fixes en utilisant le même périmètre/options.
2. Révisez le diff résultant attentivement, en priorité sur les éditions sensibles au comportement.
3. Exécutez <ruff_cmd> format sur le même périmètre.
4. Réexécutez <ruff_cmd> check.

4. Passage de remédiation manuelle

Pour les findings restants :

1. Corrigez directement dans le code quand il y a une correction claire et sûre.
2. Gardez les éditions minimales et locales.
3. Exécutez <ruff_cmd> format sur le même périmètre.
4. Réexécutez <ruff_cmd> check.

5. Politique d'ambiguïté

S'il y a plusieurs solutions valides à n'importe quelle étape, posez toujours la question à l'utilisateur avant de procéder. Ne choisissez pas silencieusement entre options équivalentes.

6. Décision de suppression (# noqa)

Utilisez la suppression seulement quand toutes les conditions sont vraies :

• La règle entre en conflit avec un comportement requis, une API publique, des conventions de framework ou des objectifs de lisibilité.
• La refactorisation serait disproportionnée par rapport à la valeur de la règle.
• La suppression est étroite et spécifique (ligne unique, code explicite quand possible).

Directives :

• Préférez # noqa: <RULE> au large # noqa.
• Ajoutez un bref commentaire de raison pour les suppressions non évidentes.
• S'il existe deux ou plus résultats valides, posez toujours la question à l'utilisateur sur l'option à préférer.

7. Boucle récursive et critères d'arrêt

Répétez les étapes 2 à 6 jusqu'à l'un de ces résultats :

• <ruff_cmd> check retourne un état propre.
• Les findings restants requièrent des décisions architecturales/produit.
• Les findings restants sont intentionnellement supprimés avec justification documentée.
• La boucle répétée ne progresse pas.

Chaque itération de boucle doit inclure <ruff_cmd> format avant le prochain <ruff_cmd> check.

Quand aucune progression n'est détectée :

1. Résumez les règles bloquées et les fichiers affectés.
2. Présentez les options valides et les compromis.
3. Demandez à l'utilisateur de choisir.

Portes de qualité

Avant de déclarer l'achèvement :

• Ruff ne retourne pas de findings inattendus pour le périmètre/options choisi.
• Tous les diffs d'autofix sont révisés pour la correction.
• Aucune suppression n'est ajoutée sans justification explicite.
• Tout fix non sûr avec impact comportemental possible est mis en avant à l'utilisateur.
• Le formatage Ruff est exécuté à chaque itération.

Contrat de sortie

À la fin de l'exécution, rapportez :

• Périmètre et options Ruff utilisés.
• Nombre d'itérations effectuées.
• Résumé des findings corrigés.
• Liste des corrections manuelles.
• Liste des suppressions avec justification.
• Findings restants, le cas échéant, et décisions utilisateur requises.

Suggestions de prompt de démarrage

• « Exécutez ruff-recursive-fix sur l'intégralité du repo avec la config par défaut. »
• « Exécutez ruff-recursive-fix seulement sur src/models, ignorer les règles DOC. »
• « Exécutez ruff-recursive-fix sur tests avec select F,E9,I et pas de fixes non sûrs. »
• « Exécutez ruff-recursive-fix sur src/data et demandez-moi avant d'ajouter du noqa. »