JoshuaKGoldberg/lint-rule-review-skill

Fähigkeit zur Überprüfung von ESLint-Regeln

Überprüfen Sie eine Lint-Regel so, wie es ein Maintainer mit Tausenden von vergangenen Überprüfungskommentaren tun würde. Die prägende Gewohnheit dieses Maintainers ist empirisch: Er liest eine Regel nicht nur, er versucht, sie zu brechen. Er löscht eine Bedingung und prüft, ob ein Test fehlschlägt, und erfindet die Syntax, an die niemand gedacht hat. Folgen Sie dieser Gewohnheit hier. Ein durch einen fehlgeschlagenen Test oder einen überlebenden Mutanten gestützter Befund ist weit mehr wert als ein plausibel klingender, und plausibel klingendes Rauschen ist der Grund, warum automatisierte Überprüfungen ignoriert werden.

Die Befunde gehen an den Benutzer, der entscheidet, was damit zu tun ist. Das Schreiben der Überprüfung in eine lokale Datei ist die gesamte Aufgabe: Das Posten auf GitHub oder das Pushen von irgendetwas geschieht nur, wenn der Benutzer separat danach fragt.

1. Verstehen Sie die Änderung

Ermitteln Sie, was überprüft wird: einen PR, einen Branch oder eine Regeldatei. Checken Sie bei einem PR dessen Head-Commit aus, wenn möglich, da spätere Schritte den Code ausführen.

Lesen Sie Folgendes, bevor Sie sich eine Meinung bilden:

• Die Regel, ihre Tests und ihre Dokumentationsseite
• Die PR-Beschreibung und das verknüpfte Issue, da eine Regel an ihrem Zweck und nicht an ihrem eigenen Algorithmus gemessen wird
• Zwei oder drei verwandte Regeln im selben Repository sowie CONTRIBUTING-Dokumente

Notieren Sie jede Frage, die der Autor in der Beschreibung stellt. Die Überprüfung sollte diese beantworten.

Die Repository-Konventionen haben Vorrang vor den Referenzen dieser Fähigkeit. Die Referenzen stammen aus mehreren Projekten. Wenn ein Muster dem widerspricht, was das Repository eindeutig tut, folgen Sie dem Repository.

Die Referenzen sind umfangreich, also lesen Sie sie nicht vollständig. Beginnen Sie mit references/index.md, das jedes Muster auflistet, und ziehen Sie nur die Abschnitte heran, die zu dieser Änderung passen. Lesen Sie auch references/extra-checks.md, das kurz ist und sich mit Tool-Fallstricken sowie Überprüfungen für Fixer, Importregeln und Flint befasst.

2. Prüfen Sie das Design der Regel

Wählen Sie aus der Liste design.md im Index je nach Art der Änderung:

• Neue Regel: ob sie dazugehört, ihr Geltungsbereich, Überschneidungen mit anderen Regeln, Typinformationen, Optionen und Platzierung in den Voreinstellungen.
• Änderung an einer etablierten Regel: Semver-Auswirkungen, verwandte Regeln, die dieselbe Änderung benötigen, und ob die Änderung dem Issue dient. Überspringen Sie den Rest.

Wenn der PR grob ist, z. B. noch keine Tests oder ein Design, das überdacht werden muss, stoppen Sie bei einer übergeordneten Überprüfung, sagen Sie dies, und überspringen Sie die Mutation, die ohne Tests nichts aussagen kann. Probieren Sie die Regel dennoch an einigen Fällen aus, da ein echter Fehler in jedem Stadium meldungswürdig ist. Detaillierte Kommentare zu Code, der sich bald ändern wird, verschwenden nur Zeit.

3. Lesen Sie jede hinzugefügte Zeile

Verwenden Sie den Index, um die Abschnitte zu ziehen, die zu dem passen, was sich geändert hat:

Geändert	Nachsehen in
Regellogik	bugs.md, simplification.md, performance.md
Fixer oder Vorschläge	fixes.md
Nachrichten	messages.md
Tests	test-method.md
Dokumentationsseiten	docs.md
Neue Namen, Optionen oder Regeln	naming.md

Führen Sie dies durch, bevor Sie versuchen, etwas zu brechen, denn die Fehlersuche übernimmt, sobald sie begonnen hat. Machen Sie sich während des Vorgehens Notizen und sortieren Sie sie in Schritt 5.

Gehen Sie die Änderung eine hinzugefügte Zeile nach der anderen durch und fragen Sie bei jeder:

• Namen: Könnten Sie erkennen, was dieser Bezeichner enthält oder tut, ohne weiterzulesen? Achten Sie auf Namen, die einen Typ und nicht einen Zweck beschreiben, und auf Namen, die die falsche Aktion beanspruchen. Wenn es ein zweites Lesen erforderte, um es zu verstehen, sagen Sie dies und schlagen Sie einen besseren Namen vor.
• Lokale Variablen: Wird diese Variable einmal verwendet, direkt nachdem sie gesetzt wurde? Schlagen Sie vor, sie zu inlinen.
• Bedingungen: Kollabiert sie? !x || x.kind !== y wird zu x?.kind !== y. Verschachtelte oder benachbarte ifs lassen sich oft zusammenfassen, und ein boolesches if gibt oft direkt zurück.
• Wächter: Kann dieser Zustand angesichts des AST und des darüberliegenden Codes wirklich eintreten?
• Wiederverwendung: Macht eine gemeinsam genutzte Utility dies bereits? Prüfen Sie dies, bevor Sie einen Helfer akzeptieren. Würde ein Helfer innerhalb von create weniger Parameter benötigen?
• Länge: Gibt es weniger Code, der dasselbe tut? Vereinfachung ist die größte Kategorie in vergangenen Überprüfungen.
• Lohnenswert: Plant dieser Code oder dieses TODO etwas, das niemand braucht? Sagen Sie, dass es wegkann.

Wenn der Code KI-gestützt aussieht, lesen Sie ihn mit einer kritischeren Brille, denn dort sammelt sich tendenziell Ballast.

Durchsuchen Sie jeden Kommentar und jeden Dokumentsatz. Die Fehlersuche verdrängt dies, obwohl es eine regelmäßige Quelle echter Überprüfungskommentare ist. Führen Sie dies daher als separaten Durchlauf über jeden hinzugefügten Kommentar und jede hinzugefügte Zeile der Dokumentation durch. Fragen Sie nicht, ob es korrekt ist, sondern ob es so, wie geschrieben, dort sein sollte:

• Wird dieser Kommentar veralten? Notizen über Testabdeckung, Historie oder das, was ein Test abdeckt, werden dies tun. Schlagen Sie daher vor, sie zu löschen.
• Wiederholt er den Code? Schlagen Sie vor, ihn zu löschen.
• Handelt es sich um einen signifikanten bekannten Workaround, z. B. einen Fork von Upstream-Code? Bitten Sie um ein TODO mit einem Issue-Link, falls vorhanden, und schlagen Sie den genauen Kommentar vor.
• Würde ein Endbenutzer diesen Dokumentsatz beachten? Implementierungsdetails gehören nicht auf die Seite.
• Enthält dieses Dokumentationsbeispiel Code, den es nicht braucht? Schlagen Sie vor, alles zu kürzen, was über das hinausgeht, was das Verhalten zeigt.
• Ist der Satz präzise? Achten Sie auf Formulierungen, die universell oder immer wahr klingen, wenn sie es nicht sind, und schlagen Sie eine Umformulierung vor.

Geben Sie diese als ```suggestion-Blöcke an. Sie sind für den Autor schnell zu akzeptieren.

Bemerken Sie, was gut ist. Notieren Sie alles, was Ihnen bei der Überprüfung geholfen hat oder etwas Kniffliges behandelt, und erwähnen Sie es explizit im Überprüfungstext oder als [Praise]-Kommentar.

4. Versuchen Sie, es zu brechen

Dieser Schritt liefert die wertvollsten Befunde, also überspringen Sie ihn nicht. Beginnen Sie damit, die vorhandenen Tests der Regel zum Laufen zu bringen, damit Sie einen funktionierenden Befehl haben, der nur die Tests dieser Regel ausführt.

Mutieren Sie die Bedingungen. Führen Sie das gebündelte Skript aus dem Repository-Stammverzeichnis aus. Es benötigt Node 22.18 oder neuer, was von der Version abweichen kann, die das Repository vorgibt. Jeder Mutant ist ein Testlauf, also führen Sie ihn im Hintergrund aus. Es bearbeitet die Regel direkt, daher muss alles, was Sie in der Zwischenzeit ausführen, eine Kopie der Regel verwenden, die unter einem temporären Namen gespeichert ist:

node <skill-dir>/scripts/mutate-conditions.ts --file <rule> --test "<test command>" --base <base ref>

--base beschränkt Mutanten auf Zeilen, die der PR geändert hat, und --diff <file> macht dasselbe mit einem Diff. Lassen Sie beide weg, um eine ganze neue Regel zu mutieren. Mutanten werden in Quellreihenfolge bis zu --max ausgeführt, standardmäßig 60. Erhöhen Sie es also, wenn die Zusammenfassung zeigt, dass einige nicht getestet wurden. Wenn die Tests aus einem Paketordner ausgeführt werden, führen Sie das Skript von dort aus. --out <file> speichert die vollständigen Ergebnisse, und eine kurze Liste der Überlebenden wird immer zuletzt ausgegeben. Es überprüft zunächst, ob die Tests fehlschlagen, wenn die Regel einen Fehler wirft, und stoppt, wenn dies nicht der Fall ist, da die Tests dann nicht die Regel ausführen. Das Skript stellt die Datei wieder her, wenn es beendet oder gestoppt wird. Wenn es abrupt beendet wird, weigert sich der nächste Lauf zu starten und gibt aus, wo das Original gespeichert ist. Vergleichen Sie also die beiden, bevor Sie die Regel ändern, da Sie sie möglicherweise in der Zwischenzeit bearbeitet haben. Wenn der Testbefehl die Regel erstellt, bauen Sie sie danach neu auf, da die Build-Ausgabe noch den letzten Mutanten enthält. Es parst mit dem typescript des Repositorys, und bei TypeScript 7 oder neuer gibt es aus, wie eine ältere Kopie mit --typescript übergeben wird.

Mutanten, die die Tests nicht bemerken, sind Überlebende: Jeder bedeutet, dass ein Test fehlt oder der Code tot ist, und Sie sollten herausfinden, welches zutrifft. Löschen Sie die Bedingung und denken Sie darüber nach, welche Eingabe sie benötigen würde. Wenn Sie keine konstruieren können, empfehlen Sie, den Code zu löschen. Wenn doch, fügen Sie es im nächsten Schritt hinzu. Als likelyTypeOnly markierte Überlebende sind bloße Null-Check-Ausgänge, die oft nur für den Compiler existieren. Sehen Sie sich diese zuletzt an, aber überprüfen Sie, ob der Zweig nicht einfach ungetestet ist. Wenn der Testrunner Typprüfungen durchführt, kann ein Mutant auch nur „fehlschlagen", weil er nicht kompiliert. Verwenden Sie daher, wo möglich, einen Befehl, der nur transpiliert.

Das Skript deckt nur häufige Mutationen ab. Probieren Sie auch von Hand alles aus, was es nicht erreichen kann und wovon der PR abhängt, z. B. das Austauschen eines Arguments gegen eine ähnliche Variable, die bereits im Gültigkeitsbereich ist.

Vergleichen Sie Head und Base. Bei einer Änderung an einer bestehenden Regel ist dies die wichtigste Überprüfung. Eine Regression in Code, der früher funktioniert hat, ist weitaus wichtiger als eine Lücke, die bereits vorhanden war, und Sie können sie nicht unterscheiden, ohne beide Versionen auszuführen. Speichern Sie die Basisversion neben der Regel, z. B. mit git show <base>:./<rule> > <rule-dir>/<name>.base-tmp.ts, oder durch Rückwärtsanwenden des Diffs. Kopieren Sie dann assets/compare-rule.test.ts neben die Tests der Regel und passen Sie die markierten Zeilen an. Es sortiert jeden Fall durch Vergleichen der Meldeanzahlen und zeichnet auch Nachrichten, Bereiche, Korrekturausgaben, Vorschläge, Abstürze und Kompilierungsfehler in jeder Testvorlage auf. Lesen Sie die Ergebnisse von CHANGED OUTPUT selbst, da eine geänderte Nachricht oder Korrektur der Fehler sein kann, und ignorieren Sie jeden Fall mit fixtureErrors, bis seine Testvorlage kompiliert. Bei einem PR, der einen Fixer hinzufügt, sind die Fix- und Vorschlagsausgabe das Wichtigste, was zu lesen ist. Setzen Sie daher expectedOutput für diese Fälle. Wenn der PR eine Option hinzufügt, setzen Sie baseOptions, damit das Schema der Basisversion den Fall akzeptiert. Ohne sie wird der Fall nur anhand des Heads beurteilt.

Bei einer neuen Regel importieren Sie sie sowohl als head als auch als base, damit die Testumgebung ok oder WRONG meldet, anstatt Versionen zu vergleichen. Wenn die Testumgebung nicht zum Plugin passt, verwenden Sie stattdessen eine temporäre Testdatei im eigenen Test-Framework des Repositorys.

Schreiben Sie adversariale Fälle. Wählen Sie die Kategorien aus references/test-cases.md, die zur Syntax und den Typen passen, die diese Regel berührt, und schreiben Sie buchstäbliche Fälle. Entscheiden Sie das korrekte Verhalten, bevor Sie jeden Fall ausführen, da Sie sonst rationalisieren, was auch immer zurückkommt. Geben Sie auch Nachrichtendaten sowie Meldeanzahlen aus, da ein falscher Typname in einer Nachricht ebenfalls ein Fehler ist. Kombinieren Sie einen Fall in neuer Syntax mit einer Kontrolle in alter Syntax, z. B. einen Symbolschlüssel mit demselben Fall unter Verwendung eines Stringschlüssels. Achten Sie auf:

• Abstürze
• Falsch positive Ergebnisse, bei denen gültiger Code gemeldet wird
• Falsch negative Ergebnisse, bei denen ungültiger Code nicht gemeldet wird
• Korrekturen, die ungültigen Code erzeugen, das Verhalten ändern oder Kommentare entfernen
• Meldebereiche, die breiter als der fehlerhafte Code sind

Behalten Sie die Fälle, die etwas aufgedeckt haben, damit sie in der Überprüfung als buchstäbliche Testfälle erscheinen können. „Buchstäblich" ist wichtig: Dieser Maintainer bittet um handgeschriebene Fälle und lehnt .map, Fabriken und generierte Tests ab.

Beweisen Sie große Vorschläge. Wenn Sie glauben, dass ein Redesign mehrere Fehler beheben würde, prototypisieren Sie es und führen Sie die vorhandenen Tests aus. „267 von 268 Tests bestehen, und hier ist der Grund, warum der andere fehlschlägt" ist weitaus nützlicher als eine Ahnung.

Aufräumen. Führen Sie git status aus und entfernen Sie jede temporäre Datei, bevor Sie fortfahren, damit das Repository wieder so ist, wie Sie es vorgefunden haben.

5. Filtern Sie die Befunde

Bevor Sie etwas schreiben, gehen Sie jeden Befund durch:

• Fehler: Fügen Sie den Fall und das tatsächliche Ergebnis hinzu. Wenn Sie ihn nicht reproduzieren konnten, streichen Sie ihn oder stufen Sie ihn zu einer [Question] herab, wenn Sie noch einen spezifischen Grund für den Verdacht haben.
• Reihenfolge: Regressionen zuerst, dann Fehler im neuen Code, dann bestehende Fehler, die der PR berührt.
• Eine Ursache: Wenn ein Redesign mehrere Fehler beheben würde, machen Sie daraus einen Kommentar und listen Sie die Fälle darin auf. Behalten Sie nur dann einen separaten Kommentar bei, wenn ein Fehler unabhängig davon seine eigene Korrektur benötigt, z. B. eine Regression.
• Umstrittene Positionen: Behandeln Sie diese als nicht blockierende Fragen: in-Prüfungen an Knoten, esquery-Verwendung, Form des Optionsschemas und import ts-Stil. Andere Maintainer haben vernünftigerweise anderer Meinung.
• Erweitern oder verschieben: Wenn eine Lücke dasselbe Konzept wie die Regel ist und echte Benutzer darauf stoßen würden, bitten Sie in diesem PR darum. Andernfalls schlagen Sie ein Folge-Issue vor.
• Option hinzufügen oder entfernen: Bitten Sie nur dann um eine Option, wenn die Regel ansonsten gültigen Code verbieten würde oder wenn ein echter Benutzer eine angefordert hat.
• Vorhandenen Code: Lassen Sie Probleme aus, die der PR nicht berührt hat, es sei denn, sie sind schwerwiegend, und markieren Sie diese als [Non-Actionable].
• Duplikate: Fassen Sie Wiederholungen zu einem Kommentar zusammen, der „hier und anderswo" sagt.

Rauschen kostet mehr als ein Fehler: Ein Autor, der an drei schwachen Kommentaren vorbeiscrollt, wird auch den echten überlesen. Blockierende Kommentare sollten nur das sein, was vor dem Merge geändert werden muss. Behalten Sie höchstens etwa acht nicht blockierende Kommentare, wählen Sie diejenigen, die den Code am meisten verbessern, und fügen Sie einen anwendungsbereiten Vorschlag hinzu, wo der Kommentar eine Änderung anfordert. Streichen Sie zuerst:

• Geschmacksfragen ohne wirklichen Gewinn an Klarheit, wie das Umformulieren einer Nachricht oder das Zusammenfassen einer Bedingung, die in Ordnung ist
• Alles, was die Beschreibung als beabsichtigt bezeichnet, z. B. Grundgerüst für geplante Arbeit
• Fehler, die Sie versucht haben, aber keinen echten Fall finden konnten, und kein spezifischer Grund mehr für den Verdacht besteht
• Leerzeichen und Zitierstil
• Anforderungen an Prozesse, die nichts bringen, wie ein Tracking-Issue für jedes kleine TODO

Nichts zu melden ist ein gutes Ergebnis. Erfinden Sie also keine Befunde, um gründlich zu wirken.

Passen Sie das Urteil an die blockierenden Kommentare an. Wenn nichts blockiert, genehmigen Sie und lassen Sie den Rest als Vorschläge. Viele Überprüfungen dieses Maintainers zu soliden PRs sind eine warme Genehmigung mit ein oder zwei kleinen Bitten.

6. Schreiben Sie die Überprüfung

Lesen Sie references/review-voice.md und schreiben Sie dann lint-rule-review-skill-<pr-or-rule>.md im aktuellen Verzeichnis, ohne es zu committen. Halten Sie den Überprüfungstext auf ein paar Sätze, gehen Sie nur länger darauf ein, um die Fragen des Autors zu beantworten oder eine Designentscheidung zu erklären. Verwenden Sie diese Struktur:

# Überprüfung von <PR oder Regel>

**Urteil:** genehmigen | Änderungen anfordern | nur übergeordnet

<Überprüfungstext, folgen Sie der Reihenfolge in review-voice.md>

## Inline-Kommentare

### `path/to/file.ts:42` · blockierend

[Bug] <Kommentar, wie er gepostet würde>

```ts
<Buchstäblicher fehlschlagender Fall oder Vorschlag>
```

Nachweis: <Was Sie ausgeführt haben und was passiert ist, oder „nicht reproduziert">

## Nicht überprüft

<Alles, was Sie nicht ausführen oder überprüfen konnten, und warum>

Markieren Sie jeden Kommentar als blocking oder non-blocking, geordnet blockierend zuerst. „Nachweis" dient dem Benutzer und würde nicht gepostet werden. Kommentieren Sie keine Punkte, die im Überprüfungstext bereits formuliert wurden.

7. Heften Sie Assets an

Kopieren Sie bei Bedarf temporäre Testdateien wie compare-rule.test.ts oder Testfälle, die Sie geschrieben haben, in den Ausgabeordner und verweisen Sie im Überprüfungstext darauf.

8. Melden Sie das Ergebnis

Geben Sie den Inhalt der Überprüfungsdatei als Text an den Benutzer zurück. Verwenden Sie keine Tools, um sie zu posten, es sei denn, der Benutzer fordert Sie dazu auf.

Referenzen

Die folgenden Referenzen werden von dieser Fähigkeit verwendet:

• references/index.md – Hauptindex aller Muster
• references/extra-checks.md – Zusätzliche Überprüfungen für Fixer, Importregeln und andere Tools
• references/test-cases.md – Vorlagen für Testfälle
• references/review-voice.md – Leitfaden zum Ton und Stil der Überprüfung
• assets/compare-rule.test.ts – Testassistent zum Vergleichen von Head und Base
• scripts/mutate-conditions.ts – Mutationsskript