vibator/vibator

Configuration de vibator

Référence : npx vibator docs configuration affiche le format de configuration et npx vibator docs rules affiche chaque règle avec ses options et valeurs par défaut. Cette skill décrit le workflow ; ces documents constituent le contrat.

La configuration est une tâche de découverte : la bonne configuration est déterminée par ce que le projet contient réellement. Inspectez d'abord, écrivez ensuite, exécutez en dernier.

Règles fondamentales

• N'affaiblissez jamais une garde pour la faire passer. Désactiver une règle, élargir son budget ou exclure un fichier parce qu'il échoue actuellement cache le problème au lieu de le corriger. Corrigez la constatation, ou laissez la règle échouer et dites-le. La seule échappatoire par ligne est // vibator-ignore: <raison>, et la raison est obligatoire.
• Configurez uniquement ce qui diffère des valeurs par défaut. Chaque règle s'exécute déjà avec sa sévérité par défaut sans aucune configuration. Une configuration qui répète chaque valeur par défaut enterre les lignes qui comptent.
• include et exclude remplacent les valeurs par défaut d'une règle. Ils ne fusionnent pas. Copiez les valeurs par défaut dont vous avez encore besoin avant de restreindre.
• Ne définissez jamais recommended: false pour faire passer une exécution. Cela désactive toutes les règles que la configuration ne nomme pas, y compris celles qui passent. Cela existe pour indiquer une sélection délibérée, et cette sélection est une décision humaine.
• Une configuration que le projet étend n'est pas à vous de modifier. Une préséance définit une norme partagée par plusieurs projets. Configurez la différence localement, ou demandez à un humain de modifier la préséance. Ne faites jamais taire une constatation en modifiant un fichier sous node_modules ; la prochaine installation le remplacera de toute façon.

Étapes

1. Partez d'un fichier valide. Si aucun vibator.json n'existe, exécutez npx vibator init ; cela écrit la ligne $schema qui donne aux éditeurs une validation. Ensuite, npx vibator list affiche chaque règle et sa valeur par défaut. Avant d'écrire vos propres règles, vérifiez si le projet étend déjà une préséance, ou s'il en existe une à étendre (un paquet de style @scope/quality dans package.json, ou la même configuration répétée dans des dépôts frères). L'étendre est préférable à la redéclarer ; voir « Construire sur une préséance partagée » ci-dessous.

2. Exécutez une fois, sans configuration : npx vibator --reporter json. Cela montre quelles règles passent, lesquelles échouent, et lesquelles ont planté par manque d'options. Lisez les comptages avant les diagnostics ; une règle avec 400 constatations nécessite une décision, pas 400 corrections aujourd'hui (voir étape 6).

3. Découvrez ce dont les règles désactivées par défaut ont besoin. Chacune est désactivée car elle ne peut pas agir sans connaissance du projet. Cherchez-les :

   • locale-parity : trouvez le répertoire des locales (locales/, i18n/, public/locales/). Notez la disposition : un répertoire par locale (layout: "directory-per-locale") ou un fichier par locale ("file-per-locale"), et quelle locale est la source.
   • codegen-drift : lisez les scripts package.json pour les générateurs (db:generate, openapi, graphql-codegen) et trouvez les chemins que chacun écrit. Configurez une entrée par générateur avec name, command, paths.
   • banned-patterns : lisez les conventions de revue du projet (CONTRIBUTING, docs de style, commentaires récurrents de revue). Chaque « ne faites jamais X » sous forme de motif devient une entrée avec son propre message, expected et fix, écrits aussi soigneusement que ceux d'une règle intégrée.
   • no-deprecated-apis : listez les tsconfigs ; un monorepo veut chaque projet qui doit être vérifié dans options.projects.

4. Reliez les documents existants du projet aux règles avec guidelines. Si le dépôt a un AGENTS.md, CLAUDE.md ou un document de style qui énonce une norme qu'une règle applique, mappez-le : "guidelines": {"AGENTS.md": ["tsdoc-coverage"]}. Utilisez le champ docs par règle uniquement lorsque la norme du projet remplace la directive livrée plutôt que d'ajouter du contexte.

5. Utilisez la forme tableau pour les normes divisées. Une règle peut s'exécuter plusieurs fois avec des globs et options différents :

   "max-file-size": [
     {"include": ["src/**"], "options": {"maxKb": 256}},
     {"include": ["assets/**"], "options": {"maxKb": 4096}}
   ]
   

6. Adoptez progressivement sur une base de code héritée avec --changed, pas en affaiblissant. Vérifiez le nouveau travail immédiatement (npx vibator --changed, ou --since origin/main en CI pour l'ensemble du diff de la pull request) pendant que le backlog diminue. Pour les règles avec beaucoup de constatations, utilisez warn en attendant : les constatations restent visibles sans bloquer. N'utilisez pas off pour dire « plus tard ».

7. Vérifiez le résultat. Exécutez npx vibator et confirmez : chaque règle activée s'exécute (une règle qui plante est un bug de configuration et son message indique ce qui manquait), les constatations restantes sont réelles, et npx vibator explain <rule> montre la bonne directive pour tout ce que vous avez remplacé.

Construire sur une préséance partagée

extends prend un chemin commençant par . ou un spécificateur de paquet, résolu par rapport au fichier qui le déclare. Les entrées ultérieures l'emportent sur les précédentes, et les paramètres du fichier lui-même l'emportent sur toutes.

{
  "extends": ["@acme/quality/vibator.json"],
  "rules": { "max-file-size": "warn" }
}

La fusion suit Biome, donc elle se comporte comme les utilisateurs de cette pile s'y attendent. Deux conséquences à bien comprendre :

• Une sévérité seule conserve tout le reste. Écrire "max-file-size": "warn" sur une préséance qui définissait maxKb et include ne modifie que la sévérité ; le budget et les globs sont hérités. Vous n'avez pas besoin de les redéclarer, et les redéclarer est la façon dont un projet dérive silencieusement de sa préséance.
• Les tableaux remplacent, ils ne concatènent pas. Pour ajouter une entrée à une liste héritée allow ou patterns, écrivez la liste complète que vous voulez. C'est délibéré : cela permet de supprimer une entrée héritée.

Écrivez uniquement la différence. Une configuration qui répète ce que la préséance dit déjà est impossible à distinguer d'une configuration qui la contredit, et la prochaine mise à jour de la préséance n'atteindra pas les champs que vous avez copiés.

Une préséance construite comme une sélection soignée définit "recommended": false et liste les règles qu'elle veut. Sous une telle préséance, les règles non nommées ne s'exécutent pas, donc vérifiez cela avant de conclure qu'une règle manque.

Les chemins des directives se résolvent de la même manière : les entrées docs et guidelines déclarées par une préséance se résolvent par rapport à la préséance, donc les constatations pointent vers les documents livrés avec elle. Vos propres chemins se résolvent toujours par rapport à la racine du projet.

Politique de sévérité

• error : règles déterministes avec quasi zéro faux positifs.
• warn : règles qui peuvent se tromper sur une base de code qu'elles n'ont pas vue (env-example-sync correspond au texte ; prefer-array-methods ne peut pas distinguer un tableau d'un Set), et adoption temporaire de règles avec un backlog important.
• off : uniquement pour les règles qui ne s'appliquent pas (pas de locales signifie pas de locale-parity), jamais comme moyen de passer.

Erreurs courantes

• Écrire include et perdre les exclusions par défaut de la règle (tests, .d.ts).
• Redéclarer les options d'une préséance à côté d'une substitution de sévérité, en supposant qu'une sévérité seule les ignore. Ce n'est pas le cas, et la copie cesse de suivre la préséance.
• Activer codegen-drift avec un générateur qui nécessite des services ou des secrets que l'environnement ne possède pas. La règle exécute la commande pour de vrai.
• Mapper chaque document sur chaque règle dans guidelines. Mappez uniquement les documents qui énoncent réellement la norme de cette règle.
• Modifier la configuration pour mettre fin à une exécution qui échoue au lieu de corriger les constatations. Si un humain a demandé la porte, seul un humain décide de l'abaisser.