recurspec

RecurSpec est un package Node.js sous licence MIT, à un stade précoce, qui teste les chemins de récupération dans les outils en ligne de commande. Là où un test conventionnel se contenterait d'affirmer qu'un message d'erreur est affiché, RecurSpec vérifie que la commande suggérée par le message corrige réellement le problème, afin que les utilisateurs puissent véritablement s'en sortir. Fonctionnement Un cas de test est décrit de manière déclarative dans un fichier recurspec.yml. Chaque cas déclare la commande à exécuter, l'échec attendu (par exemple, un code de sortie non nul et une sous-chaîne stderr), la provenance de l'instruction de récupération et une étape de vérification. La vérification peut relancer la commande originale et exiger un code de sortie zéro, confirmant ainsi que la boucle de récupération se ferme plutôt que de simplement constater la présence du conseil. Prise en main Le projet nécessite Node.js 22 ou une version ultérieure ainsi que pnpm. Il s'installe comme une dépendance de développement, puis s'utilise via trois commandes principales : une étape init qui écrit une configuration de démarrage contenant un exemple Node.js exécutable, une étape validate et une étape test. La démo incluse mélange délibérément des chemins de récupération réussis et défectueux. Interface en ligne de commande Le CLI expose les commandes test, validate, init, explain et discover. La commande test propose des options pour sélectionner un cas ou un tag, choisir un format de rapport (human, json, junit ou markdown), un affichage détaillé, un comportement fail-fast, un seed et un dry run. Les codes de sortie sont définis comme 0 pour tous les succès, 1 pour un contrat échoué et 2 pour des erreurs de configuration ou d'utilisation. Les rapporteurs JSON, JUnit et Markdown sont destinés aux pipelines CI et aux commentaires de pull-request. Une API programmatique est également disponible via runRecurSpec. Ce qu'il détecte L'outil cible les incohérences entre un message d'erreur et ses instructions : des commandes suggérées qui n'existent plus, des étapes de récupération incomplètes, des commandes qui réussissent sans résoudre le problème original, des conseils menant à une autre erreur, des boucles d'instructions, et des instructions ambiguës ou dangereuses. Récupération par tentative et par objectif Deux formes de récupération sont supportées. Dans la récupération de type retry, la suppression d'un blocage permet à la commande originale de réussir lors d'une seconde tentative. Dans la récupération par objectif (goal recovery), la commande suggérée remplace entièrement l'opération échouée, de sorte que l'objectif de l'utilisateur est atteint même si le relancement de la commande originale échouerait toujours. Le README note que le travail sur les cas Cargo a mis en évidence cette distinction et a conduit à la vérification basée sur les objectifs. Compatibilité réelle La suite de compatibilité inclut des cas tirés de Git, Cargo et npm, couvrant des situations telles qu'une identité Git manquante, la suppression d'une branche, des conseils de pull divergents, un répertoire de projet Cargo existant et un script npm manquant. Les résultats incluent des conseils ambiguës (plusieurs commandes exclusives ou requises), la récupération par objectif et des messages purement informatifs qui sont correctement ignorés. Les outils manquants sont ignorés lors de l'exécution de la suite. Modèle de sécurité Les commandes de récupération sont analysées et vérifiées avant l'exécution. Le chaînage de shell, la redirection, la substitution de commande et les commandes destructives connues sont bloqués par défaut, et chaque cas s'exécute dans un espace de travail temporaire isolé. Le README précise que le backend local n'impose pas de sandboxing réseau au niveau de l'OS, donc un paramètre deny-network reste consultatif jusqu'à l'existence d'un backend par conteneur. Limitations et statut La documentation liste trois limitations : l'absence d'isolation réseau au niveau de l'OS dans le backend local, la nécessité d'une entrée standard scriptée lors du test de programmes TTY interactifs (le support complet PTY est prévu pour le futur), et une dépendance aux outils affichant des conseils recherchables via grep, les conseils ambiguës ou manquants étant signalés plutôt que devinés. RecurSpec est décrit comme étant à un stade précoce, et la configuration ainsi que l'API publique peuvent changer avant une version 1.0. Des documentations distinctes couvrent la configuration, l'extraction, la sécurité, les rapporteurs et la découverte.