Auf der Regeln-Seite unter /rules erstellt, bearbeitet, veröffentlicht und archiviert ihr die eigenen Regeln eurer Organisation und durchsucht den eingebauten Plattform-Regelkatalog nach Regeln zur Wiederverwendung. Die Seite hat zwei Tabs: Meine für die Regeln eurer Organisation und Beispiele für den eingebauten Katalog.
Was eine Regel ist
Eine Regel ist eine eigenständige, versionierte Analysevorschrift. Sie besteht aus einer .ccr-Datei (der eigentlichen Regellogik in der CodeCharter-DSL) und einer optionalen Spec-Datei (Testbeispiele, die belegen, dass die Regel das Richtige erkennt). Jede Regel hat einen unveränderlichen Slug, einen optionalen Anzeigenamen und einen Standard-Schweregrad (Info, Warnung oder Fehler).
Regeln werden separat versioniert und über Profile in CI-Runs eingebunden. Mit der Veröffentlichung erhält eine Regel ihre SemVer-Version, über die CI-Pipelines sie per Profil referenzieren.
Der Regelkatalog
Der Tab Meine listet die eigenen Regeln eurer Organisation als Karten, jede mit Name, Slug, Kategorie, Schweregrad und Status. Der Tab Beispiele zeigt dieselbe Katalogansicht über CodeCharters kuratierte eingebaute Regeln, die ihr durchsuchen und in eure eigenen Regeln übernehmen könnt. Wie ihr den Katalog durchsucht und übernehmt, steht unter Der Regelkatalog.
Filtern und Suchen
Das Suchfeld durchsucht Name, Kategorie und Regelinhalt; es ist mit 300 ms Debounce versehen, sodass die Liste beim Tippen aktualisiert wird, ohne unnötige Anfragen zu erzeugen. Beide Tabs bieten die Facetten Kategorie und Schweregrad, mit denen ihr die Ergebnisse eingrenzt.
Im Tab Meine kommt zusätzlich ein Status-Filter hinzu (Alle, Entwurf, Veröffentlicht, Archiviert); stellt ihn auf Archiviert, um zuvor archivierte Regeln wiederzufinden. Außerdem gibt es den Schalter Ohne Spec, der auf Regeln ohne Testspezifikation filtert, sowie eine Tags-Facette.
Neue Regel anlegen
Wählt im Tab Meine oben rechts Neue Regel, um das Erstellungsformular zu öffnen. Ihr wählt einen Slug (nach der Erstellung unveränderlich), einen optionalen Anzeigenamen und einen Standard-Schweregrad. Die Regel startet ohne veröffentlichte Version und ohne Entwurf.
Regel duplizieren oder übernehmen
Statt eine Regel von Grund auf neu zu schreiben, wählt Duplizieren bei einer eigenen Regelkarte im Tab Meine oder Übernehmen bei einer Katalogregel im Tab Beispiele, um Quelltext, Spec, Kategorie und Schweregrad als neuen Entwurf unter einem selbst gewählten Slug zu kopieren. Den Übernahme-Ablauf im Detail findet ihr unter Der Regelkatalog.
Regel editieren
Wählt im Tab Meine auf einer Regelkarte Im Editor öffnen, um den Regel-Editor zu öffnen. Der Editor gliedert sich in zwei Hälften:
Der linke Editor enthält die .ccr-Datei, die eigentliche Regellogik in der CodeCharter-DSL. Syntaxfehler werden inline unterstrichen. Ihr könnt die Datei frei editieren; Änderungen werden automatisch als Entwurf gespeichert.
Der rechte Spec-Editor enthält die Testspezifikation im Markdown-Format: Code-Beispiele werden unter den Überschriften ## hits und ## misses in Positiv- und Negativ-Beispiele gegliedert, die belegen, dass die Regel das Richtige erkennt. Über den Vorschau-Schalter in der Kopfzeile des Bereichs lässt sich das Markdown gerendert anzeigen. Regeln ohne Spec findet ihr über den Filter Ohne Spec in der Regelliste.
Der AST-Inspector liegt im AST-Tab des einklappbaren Tools-Panels rechts neben den Editoren. Er zeigt den C#-Syntaxbaum des Beispielcodes aus dem aktuell ausgewählten Spec-Testfall und hilft euch zu prüfen, ob eure Query die richtigen Elemente trifft.
Spec-Run und Debugging
Spec ausführen
Wählt im Editor Specs ausführen, um alle Spec-Testfälle gegen die aktuell gespeicherte Fassung auszuführen. Speichert den Entwurf also zuerst, damit der Lauf eure letzten Änderungen berücksichtigt. Das Ergebnis erscheint im unteren Panel: Jeder Testfall erhält ein Status-Badge (Bestanden, Fehlgeschlagen, Fehler oder Timeout).
Trace-Drawer
Wählt die Zeile eines fehlgeschlagenen oder fehlerhaften Testfalls, um den Trace-Drawer zu öffnen. Der Trace-Tab zeigt einen Baum der Auswertungsschritte mit Bestanden/Fehlgeschlagen-Markierung und Details je Schritt, und der Diff-Tab stellt das erwartete dem tatsächlichen Ergebnis gegenüber, sodass ihr seht, warum ein Finding ausgelöst (oder nicht ausgelöst) wurde.
Fehler verstehen
Häufige Ursachen für Testfehler:
- Query trifft die falschen Elemente: Die Query liefert mehr oder weniger Treffer als erwartet. Mit dem AST-Inspector prüft ihr, welche Elemente tatsächlich gematcht werden. Wenn zum Beispiel eine Methode markiert werden soll, die Query aber auf dem deklarierenden Typ matcht, ändert ihr die Root-Collection von
TypesaufMethods. - Fehlende Negativ-Beispiele: Ohne Gegenbeispiele kann die Regel versehentlich zu weit greifen.
Regeln in VS Code bearbeiten
Für längere Bearbeitungssitzungen könnt ihr den aktuellen Entwurf aus dem Portal herausnehmen, in VS Code daran arbeiten und das Ergebnis als Entwurf zurückspielen.
Voraussetzungen
- Die CodeCharter-VS-Code-Extension ist installiert. Sie registriert den Link-Handler, der den Entwurf entgegennimmt, und stellt den Push-Befehl bereit.
- Das Extension-Setting
codecharter.portalBaseUrlzeigt auf das Portal, das ihr verwendet. Der Standardwert isthttps://codecharter.tools; ihr müsst ihn nur ändern, wenn ihr gegen eine andere Portal-Adresse arbeitet. - Euer Browser darf
vscode://-Links öffnen (die meisten Browser zeigen beim ersten Mal eine Bestätigungsabfrage).
In VS Code meldet ihr euch nicht am Portal an. Der Übergabe-Link enthält ein kurzlebiges Zugriffstoken, das nur für diese eine Regel gilt und nach fünf Minuten abläuft.
Entwurf in VS Code öffnen
Öffnet im Regel-Editor das Überlauf-Menü (⋮) und wählt In VSCode öffnen. Die Aktion wird verfügbar, sobald der Entwurf mindestens einmal gespeichert wurde. Speichert einen ganz neuen Entwurf also zuerst.
VS Code öffnet den aktuellen Entwurf in zwei Editoren nebeneinander: links die .ccr-Quelldatei, daneben die Spec (Markdown). Falls VS Code nach dem Regel-Slug fragt, gebt ihr den Slug genau so ein, wie er im Portal angezeigt wird. Eine Benachrichtigung bestätigt, welche Regel und welche Entwurfsrevision geladen wurden, und erinnert an den Push-Befehl.
Lokal bearbeiten und testen
Bearbeitet Quelldatei und Spec in VS Code mit voller DSL-Unterstützung (Highlighting, Autovervollständigung, Inline-Validierung). Die beiden Übergabe-Editoren sind zunächst ungespeicherte Dokumente im Arbeitsspeicher. Spec-Tests laufen gegen Dateien auf der Festplatte: Um lokal zu testen, speichert ihr eine Kopie der Inhalte als <name>.ccr und <name>.spec.md nebeneinander und führt codecharter test darauf aus, oder ihr nutzt die Spec-Befehle der Extension auf den gespeicherten Dateien.
Entwurf ans Portal senden
Wenn ihr fertig seid, führt den Befehl CodeCharter: Push to portal aus. Er schickt den aktuellen Inhalt der beiden Übergabe-Editoren zurück ans Portal, wo er den Entwurf der Regel ersetzt.
Der Push aktualisiert immer nur den Entwurf. Er veröffentlicht nie eine Version: Ihr prüft das Ergebnis im Regel-Editor des Portals, führt dort die Specs aus und veröffentlicht wie gewohnt (siehe den Abschnitt Veröffentlichen weiter unten). Nach einem erfolgreichen Push könnt ihr in VS Code weiterarbeiten und den Entwurf erneut übertragen.
Konflikte und abgelaufene Links
Wenn sich der Entwurf auf Portalseite geändert hat, nachdem ihr ihn abgeholt habt (zum Beispiel weil jemand ihn im Portal-Editor bearbeitet hat, der automatisch speichert), wird der Push abgelehnt und VS Code zeigt eine Warnung, dass der Entwurf anderweitig geändert wurde. Dabei wird nichts überschrieben: Das Portal behält seinen aktuellen Entwurf. Holt den Entwurf über In VSCode öffnen erneut ab und übertragt eure Änderungen in die frische Kopie.
Ist das Zugriffstoken aus dem Übergabe-Link abgelaufen, schlägt der Push mit einer entsprechenden Meldung fehl. Startet über In VSCode öffnen im Portal eine neue Übergabe.
Veröffentlichen
Sobald der Entwurf alle Spec-Tests besteht, könnt ihr eine neue Version veröffentlichen.
SemVer wählen
Wählt Veröffentlichen. Das Formular schlägt die nächste Patch-Version vor (z.B. 1.0.0 bei einer neuen Regel oder 1.2.4 nach 1.2.3). Ihr könnt Minor oder Major wählen, wenn die Änderung entsprechend bedeutsam ist, oder eine eigene Versionsnummer eingeben. SemVer folgt dabei dem üblichen Schema: Patch für Bugfixes und kleine Anpassungen, Minor für neue Erkennungsfeatures ohne Breaking Changes, Major für Breaking Changes. Ist der Entwurf inhaltlich identisch mit der zuletzt veröffentlichten Version, zeigt das Formular vor dem Veröffentlichen eine Warnung an.
Versionshinweise
Das Veröffentlichungsformular enthält ein Pflichtfeld Versionshinweise (Markdown, bis 4 KB); solange es leer ist, lässt sich nicht veröffentlichen. Die Hinweise werden zusammen mit der veröffentlichten Version gespeichert. Haltet die Hinweise kurz und prägnant: ein Satz, was sich geändert hat und warum, ist meistens genug.
Folge-Aktion: Profil-Bulk-Publish
Nach dem Veröffentlichen zeigt das Portal einen Dialog mit allen Profilen, die noch auf eine ältere Version dieser Regel verweisen. Wählt die gewünschten Profile aus und wählt Entwürfe erstellen: Jedes ausgewählte Profil erhält einen neuen Entwurf mit der aktualisierten Regel-Referenz. Diese Profilentwürfe prüft und veröffentlicht ihr anschließend wie gewohnt. Das ist der übliche Weg, um eine neue Regel-Version in die CI-Pipelines zu bringen.
Archivieren
Öffnet die Detailseite der Regel (Button Details auf ihrer Karte) und wählt Archivieren. Ein Bestätigungsdialog weist darauf hin, dass bestehende veröffentlichte Versionen weiterhin über Lockfiles auflösbar bleiben. Nach dem Archivieren verschwindet die Regel aus der Standardansicht; über die Status-Facette Archiviert im Tab Meine findet ihr sie wieder. Hat die Regel einen offenen Entwurf, ist das Archivieren blockiert, bis ihr diesen Entwurf veröffentlicht oder verworfen habt.
Slugs sind unveränderlich. Wenn ihr einen anderen Slug benötigt, kopiert die Regel mit Duplizieren unter dem neuen Slug und archiviert die alte, das übernimmt auch Quelltext und Spec, sodass ihr nicht bei null anfangt.
Reaktivieren
Das Archivieren ist vollständig reversibel. Öffnet die Detailseite der archivierten Regel und wählt Wiederherstellen. Die Regel erscheint danach wieder in der Standardansicht von Meine; ein neuer Entwurf oder eine neue Veröffentlichung ist anschließend möglich.
Versionen
Versionshistorie
Öffnet die Detailseite einer Regel (Button Details auf ihrer Karte) und wechselt dort auf den Tab Versionsverlauf. Er zeigt jede veröffentlichte Version mit SemVer-Nummer, Veröffentlichungsdatum, Engine-Version und Spec-Status. Zurückgezogene Versionen tragen ein yanked-Badge.
Snapshot-Ansicht
Wählt in der Zeile einer Version die Aktion Snapshot, um den Snapshot zu öffnen: die exakte .ccr-Datei und Spec, so wie sie zum Zeitpunkt der Veröffentlichung aussahen. Snapshots sind unveränderlich: Ihr könnt sie lesen, aber nicht bearbeiten.
Diff zwischen Versionen
Öffnet den Snapshot einer Version und wählt Mit anderer Version vergleichen…, um die Vergleichsversion zu wählen. Die Diff-Ansicht stellt beide Versionen in drei Tabs nebeneinander dar: Quellcode (.ccr), Spezifikation (.spec.md) und Metadaten, und lässt euch die Von- und Nach-Version jederzeit umstellen. So seht ihr auf einen Blick, was sich zwischen zwei Releases geändert hat.
Prädikat-Katalog im Editor
Wenn ihr eine neue .ccr-Datei schreibt oder eine bestehende überarbeitet, bietet der Regel-Editor rechts neben dem Code-Bereich den Prädikat-Katalog im Tools-Panel an. Er listet die in Queries verwendbaren DSL-Operationen, gruppiert nach Kategorie (String, Collection, Operator), jeweils mit Signatur, kurzer Beschreibung und einem Anwendungsbeispiel. So müsst ihr den Katalog nicht auswendig kennen.
Katalog öffnen und filtern
Öffnet den Tab Prädikate im einklappbaren Tools-Panel rechts, um den Katalog anzuzeigen. Ein Suchfeld am oberen Rand filtert die Einträge nach Name, Signatur, Beschreibung oder Kategorie. Ein Klick auf einen Eintrag klappt dessen Details auf; der Button In Editor einfügen übernimmt das Anwendungsbeispiel in den .ccr-Editor.
Root-Collections auf einen Blick
| Root | Enthält | Typischer Einstiegspunkt |
|---|---|---|
Types |
TypeModel |
Alle Klassen, Structs, Interfaces, Enums |
Methods |
MethodModel |
Alle Methoden aller Typen |
Properties |
PropertyModel |
Alle Properties |
Fields |
FieldModel |
Alle Felder |
AllBodies |
IHasBodySyntax |
Jeder Methoden-/Konstruktor-/Property-Accessor-Body, für Statement-Level-Facts |
Die vollständige Property-Liste jedes Modell-Typs findet ihr unter Prädikat-Katalog.
Snippet-Palette
Die Snippet-Palette hält fertige DSL-Bausteine bereit, die ihr per Klick in den Editor einfügt. Sie ist in Kategorien gegliedert.
Palette öffnen
Wählt in der Werkzeugleiste des Quellcode-Bereichs den Button Snippets (oder drückt Ctrl+Shift+S), um die Snippet-Palette zu öffnen. Die Snippets sind nach Kategorien geordnet: Regel-Grundgerüste, Prädikate und Spec-Testfälle.
Snippets einfügen
Ein Klick auf einen Snippet-Namen zeigt eine Vorschau; der Button Snippet einfügen übernimmt die Vorlage anschließend an der aktuellen Cursor-Position. Die Vorlage enthält vorbelegte Platzhalter, durch die ihr mit Tab springt und die ihr direkt ersetzen könnt.
Eigene Snippets
Das Portal speichert keine nutzerdefinierten Snippets. Um eine ganze Regel wiederzuverwenden, nutzt ihr stattdessen Duplizieren (siehe "Regel duplizieren oder übernehmen" oben); für ein kleineres Muster kopiert ihr den passenden DSL-Block aus einer bestehenden Regel in den Editor der neuen Regel und passt ihn an.