vibator/vibator

Konfiguration von vibator

Referenz: npx vibator docs configuration gibt das Konfigurationsformat aus und npx vibator docs rules gibt jede Regel mit ihren Optionen und Standardwerten aus. Dieser Skill ist der Workflow; diese Dokumente sind der Vertrag.

Die Konfiguration ist eine Entdeckungsaufgabe: Die richtige Konfiguration wird dadurch bestimmt, was das Projekt tatsächlich enthält. Erst inspizieren, dann schreiben, dann ausführen.

Grundregeln

• Schwäche niemals ein Tor, um es passieren zu lassen. Eine Regel auszuschalten, ihr Budget zu erweitern oder eine Datei auszuschließen, weil sie aktuell fehlschlägt, versteckt das Problem, anstatt es zu beheben. Behebe den Befund oder lass die Regel fehlschlagen und sag es. Der einzige Escape pro Zeile ist // vibator-ignore: <Begründung>, und die Begründung ist erforderlich.
• Konfiguriere nur, was von den Standardeinstellungen abweicht. Jede Regel läuft bereits mit ihrer eigenen Standard-Schwere, ohne jegliche Konfiguration. Eine Konfiguration, die jeden Standard wiederholt, vergräbt die Zeilen, die zählen.
• include und exclude ersetzen die Standardeinstellungen einer Regel. Sie führen diese nicht zusammen. Kopiere die Standardeinstellungen, die du noch behalten möchtest, bevor du eingrenzt.
• Setze niemals recommended: false, um einen Durchlauf zu bestehen. Es deaktiviert jede Regel, die die Konfiguration nicht nennt, auch die bestehenden. Es existiert, um eine bewusste Auswahl zu treffen, und diese Auswahl ist eine menschliche Entscheidung.
• Eine Konfiguration, die das Projekt erweitert, darfst du nicht bearbeiten. Ein Preset definiert einen Standard, den mehrere Projekte teilen. Konfiguriere den Unterschied lokal oder frage einen Menschen, das Preset zu ändern. Unterdrücke niemals einen Befund, indem du eine Datei unter node_modules bearbeitest; die nächste Installation ersetzt sie ohnehin.

Schritte

1. Beginne mit einer gültigen Datei. Wenn keine vibator.json existiert, führe npx vibator init aus; es schreibt die $schema-Zeile, die Editoren eine Validierung ermöglicht. Dann zeigt npx vibator list jede Regel und ihren Standard. Bevor du eigene Regeln schreibst, überprüfe, ob das Projekt bereits ein Preset erweitert oder ob eines existiert, das erweitert werden kann (ein @scope/quality-Stil-Paket in package.json oder dieselbe Konfiguration, die in benachbarten Repositories wiederholt wird). Es zu erweitern ist besser, als es zu wiederholen; siehe "Aufbau auf einem gemeinsamen Preset" unten.

2. Führe einmal unkonfiguriert aus: npx vibator --reporter json. Dies zeigt, welche Regeln bestehen, welche fehlschlagen und welche aufgrund fehlender Optionen abgestürzt sind. Lese zuerst die Anzahlen, dann die Diagnosen; eine Regel mit 400 Befunden braucht eine Entscheidung, nicht 400 Korrekturen heute (siehe Schritt 6).

3. Entdecke, was die standardmäßig deaktivierten Regeln benötigen. Jede ist deaktiviert, weil sie ohne Projektkenntnis nicht handeln kann. Suche danach:

   • locale-parity: Finde das Locales-Verzeichnis (locales/, i18n/, public/locales/). Notiere das Layout: ein Verzeichnis pro Locale (layout: "directory-per-locale") oder eine Datei pro Locale ("file-per-locale"), und welche Locale die Quelle ist.
   • codegen-drift: Lies die Skripte in package.json nach Generatoren (db:generate, openapi, graphql-codegen) und finde die Pfade, die jeder schreibt. Konfiguriere einen Eintrag pro Generator mit name, command, paths.
   • banned-patterns: Lies die Review-Konventionen des Projekts (CONTRIBUTING, Stil-Dokumente, wiederkehrende Review-Kommentare). Jedes musterartige "Tu niemals X" wird zu einem Eintrag mit eigener message, expected und fix, so sorgfältig geschrieben wie eine eingebaute Regel.
   • no-deprecated-apis: Liste die tsconfigs auf; ein Monorepo möchte jedes Projekt, das überprüft werden soll, in options.projects.

4. Verbinde vorhandene Projektdokumente mit Regeln über guidelines. Wenn das Repository eine AGENTS.md, CLAUDE.md oder ein Stil-Dokument hat, das einen Standard festlegt, den eine Regel durchsetzt, ordne es zu: "guidelines": {"AGENTS.md": ["tsdoc-coverage"]}. Verwende das docs-Feld pro Regel nur, wenn der Standard des Projekts die mitgelieferte Richtlinie ersetzt, anstatt Kontext hinzuzufügen.

5. Verwende die Array-Form für geteilte Standards. Eine Regel kann mehrmals mit unterschiedlichen Globs und Optionen ausgeführt werden:

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

6. Führe inkrementell auf einer Legacy-Codebasis mit --changed ein, nicht durch Schwächung. Überprüfe neue Arbeit sofort (npx vibator --changed, oder --since origin/main in CI für den gesamten Diff des Pull Requests), während der Rückstand schrumpft. Verwende bei Regeln mit vielen Befunden vorübergehend warn: Befunde bleiben sichtbar, ohne zu blockieren. Verwende nicht `off", um "später" zu meinen.

7. Überprüfe das Ergebnis. Führe npx vibator aus und bestätige: Jede aktivierte Regel läuft (eine abgestürzte Regel ist ein Konfigurationsfehler und ihre Nachricht sagt, was fehlte), die verbleibenden Befunde sind echt, und npx vibator explain <rule> zeigt die richtige Richtlinie für alles, was du überschrieben hast.

Aufbau auf einem gemeinsamen Preset

extends nimmt einen Pfad, der mit . beginnt, oder einen Paketspezifizierer, aufgelöst relativ zur Datei, die ihn deklariert. Spätere Einträge gewinnen über frühere, und die eigenen Einstellungen der Datei gewinnen über alle.

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

Die Zusammenführung folgt Biome, verhält sich also so, wie Nutzer dieses Stacks es erwarten. Zwei Konsequenzen, die es richtig zu machen gilt:

• Eine bloße Schwere behält alles andere bei. "max-file-size": "warn" über einem Preset, das maxKb und include gesetzt hat, ändert nur die Schwere; das Budget und die Globs werden vererbt. Du musst sie nicht wiederholen, und sie zu wiederholen ist, wie ein Projekt still vom Preset abweicht.
• Arrays ersetzen, sie verketten nicht. Um einen Eintrag zu einer vererbten allow- oder patterns-Liste hinzuzufügen, schreibe die gesamte Liste, die du möchtest. Dies ist beabsichtigt: Es macht das Entfernen eines vererbten Eintrags möglich.

Schreibe nur den Unterschied. Eine Konfiguration, die wiederholt, was das Preset bereits sagt, ist nicht von einer zu unterscheiden, die widerspricht, und das nächste Preset-Update wird die kopierten Felder nicht erreichen.

Ein Preset, das als kuratierte Auswahl erstellt wurde, setzt `"recommended": false" und listet die Regeln auf, die es möchte. Unter einem solchen Preset laufen nicht benannte Regeln nicht, also überprüfe es, bevor du schließt, dass eine Regel fehlt.

Richtlinienpfade werden auf die gleiche Weise aufgelöst: docs- und guidelines-Einträge, die von einem Preset angegeben werden, werden gegen das Preset aufgelöst, sodass Befunde auf die mitgelieferten Dokumente verweisen. Deine eigenen Pfade werden weiterhin gegen das Projektstammverzeichnis aufgelöst.

Schweregrad-Richtlinie

• error: Deterministische Regeln mit nahezu null Fehlalarmen.
• warn: Regeln, die bei einer Codebasis, die sie nicht gesehen haben, falsch liegen können (env-example-sync vergleicht Text; prefer-array-methods kann ein Array nicht von einem Set unterscheiden), und vorübergehende Einführung von Regeln mit einem großen Rückstand.
• off: Nur für Regeln, die nicht zutreffen (keine Locales bedeutet keine locale-parity), niemals als Mittel, um zu bestehen.

Häufige Fehler

• include schreiben und die standardmäßigen Ausschlüsse der Regel verlieren (Tests, .d.ts).
• Die Optionen eines Presets neben einer Schweregrad-Überschreibung wiederholen, in der Annahme, dass eine bloße Schwere sie verwirft. Das tut sie nicht, und die Kopie hört auf, das Preset zu verfolgen.
• codegen-drift aktivieren mit einem Generator, der Dienste oder Geheimnisse benötigt, die die Umgebung nicht hat. Die Regel führt den Befehl tatsächlich aus.
• Jedes Dokument auf jede Regel in guidelines abbilden. Bilde nur Dokumente ab, die tatsächlich den Standard dieser Regel festlegen.
• Die Konfiguration bearbeiten, um einen fehlschlagenden Durchlauf zu beenden, anstatt die Befunde zu beheben. Wenn ein Mensch das Tor verlangt hat, entscheidet nur ein Mensch, es zu senken.