Die Regeln-Seite unter /rules listet alle aktiven Regeln Ihres Accounts. Von hier aus können Sie neue Regeln anlegen, ihren Status verfolgen, bestehende Regeln editieren und nicht mehr benötigte Regeln archivieren.
Was eine Rule ist
Eine Rule ist eine eigenständige, versionierte Analysevorschrift. Sie besteht aus einer .cgr-Datei (der eigentlichen Regellogik in der CodeCharter-DSL) und einer optionalen Spec-Datei (Testbeispiele, die belegen, dass die Regel das Richtige erkennt). Jede Rule 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. Solange eine Rule nicht veröffentlicht ist, gibt es keine SemVer-Version und kein CI kann sie referenzieren.
Die Regelliste
Jede Tabellenzeile zeigt:
- Slug: der unveränderliche, URL-sichere Bezeichner und ein optionaler Anzeigename.
- Letzte Version: die zuletzt veröffentlichte SemVer-Version. Bei unveröffentlichten Regeln erscheint ein Gedankenstrich.
- Schweregrad: der Standard-Schweregrad, den die Regel bei einem Fund ausgibt (Info, Warnung oder Fehler).
- Status: entweder ein Entwurf-Badge, wenn die Regel einen unveröffentlichten Entwurf hat, oder ein Veröffentlicht-Badge mit dem Veröffentlichungsdatum.
- In Profilen: die Anzahl veröffentlichter Profilversionen, die auf diese Regel verweisen. Ein Klick auf das Badge öffnet die Regeldetailseite.
Filtern und Suchen
Die Filterleiste erlaubt es, die Liste nach Freitext (auf Slug und Anzeigename angewendet), Schweregrad, Status und Tags einzuschränken. Das Suchfeld ist mit 300 ms Debounce versehen, sodass die Liste beim Tippen aktualisiert wird, ohne unnötige Anfragen zu erzeugen.
Der Schalter Ohne Spec filtert auf Regeln ohne Testspezifikation, praktisch um den Erstellungsfortschritt zu verfolgen.
Neue Regel anlegen
Klicken Sie oben rechts auf Neue Regel, um das Erstellungsformular zu öffnen. Sie wählen 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 editieren
Öffnen Sie das Kebab-Menü (⋮) in der jeweiligen Zeile und wählen Sie Bearbeiten, um den Regel-Editor zu öffnen. Der Editor gliedert sich in zwei Hälften:
Der linke Editor enthält die .cgr-Datei, die eigentliche Regellogik in der CodeCharter-DSL. Syntaxfehler werden inline unterstrichen. Sie können 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 finden Sie ü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 Ihnen zu prüfen, ob Ihre Query die richtigen Elemente trifft.
Spec-Run und Debugging
Spec ausführen
Klicken Sie im Editor auf Specs ausführen, um alle Spec-Testfälle gegen die aktuell gespeicherte Fassung auszuführen. Speichern Sie den Entwurf also zuerst, damit der Lauf Ihre letzten Änderungen berücksichtigt. Das Ergebnis erscheint im unteren Panel: Jeder Testfall erhält ein Status-Badge (Bestanden, Fehlgeschlagen, Fehler oder Timeout).
Trace-Drawer
Klicken Sie auf 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, der Diff-Tab stellt das erwartete dem tatsächlichen Ergebnis gegenüber, sodass Sie sehen, 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üfen Sie, welche Elemente tatsächlich gematcht werden. Wenn zum Beispiel eine Methode markiert werden soll, die Query aber auf dem deklarierenden Typ feuert, ändern Sie 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önnen Sie 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 Sie verwenden. Der Standardwert isthttps://codecharter.tools; Sie müssen ihn nur ändern, wenn Sie gegen eine andere Portal-Adresse arbeiten. - Ihr Browser darf
vscode://-Links öffnen (die meisten Browser zeigen beim ersten Mal eine Bestätigungsabfrage).
In VS Code melden Sie sich 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
Öffnen Sie im Regel-Editor das Überlauf-Menü (⋮) und wählen Sie In VSCode öffnen. Die Aktion wird verfügbar, sobald der Entwurf mindestens einmal gespeichert wurde; ein ganz neuer, noch nie gespeicherter Entwurf lässt sich noch nicht übergeben.
VS Code öffnet den aktuellen Entwurf in zwei Editoren nebeneinander: links die .cgr-Quelldatei, daneben die Spec (Markdown). Falls VS Code nach dem Regel-Slug fragt, geben Sie 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
Bearbeiten Sie 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, speichern Sie eine Kopie der Inhalte als <name>.cgr und <name>.spec.md nebeneinander und führen Sie codecharter test darauf aus, oder nutzen Sie die Spec-Befehle der Extension auf den gespeicherten Dateien.
Push to portal
Wenn Sie fertig sind, führen Sie 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: Sie prüfen das Ergebnis im Regel-Editor des Portals, führen dort die Specs aus und veröffentlichen wie gewohnt (siehe den Abschnitt Publishen weiter unten). Nach einem erfolgreichen Push können Sie in VS Code weiterarbeiten und erneut pushen.
Konflikte und abgelaufene Links
Wenn sich der Entwurf auf Portalseite geändert hat, nachdem Sie ihn abgeholt haben (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. Holen Sie den Entwurf über In VSCode öffnen erneut ab und übertragen Sie Ihre Änderungen in die frische Kopie.
Ist das Zugriffstoken aus dem Übergabe-Link abgelaufen, schlägt der Push mit einer entsprechenden Meldung fehl. Starten Sie über In VSCode öffnen im Portal eine neue Übergabe.
Publishen
Sobald der Entwurf alle Spec-Tests besteht, können Sie eine neue Version veröffentlichen.
SemVer wählen
Klicken Sie auf 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). Sie können 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.
Release Notes
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. Halten Sie 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 Rule verweisen. Wählen Sie die gewünschten Profile aus und klicken Sie auf Entwürfe erstellen: Jedes ausgewählte Profil erhält einen neuen Entwurf mit der aktualisierten Rule-Referenz. Diese Profilentwürfe prüfen und veröffentlichen Sie anschließend wie gewohnt. Das ist der übliche Weg, um eine neue Rule-Version in die CI-Pipelines zu bringen.
Archivieren
Öffnen Sie das Kebab-Menü (⋮) in der jeweiligen Zeile und wählen Sie Archivieren. Ein Bestätigungsdialog weist darauf hin, dass bestehende veröffentlichte Versionen weiterhin über Lockfiles auflösbar bleiben. Nach dem Archivieren erscheint die Regel nicht mehr in der aktiven Liste.
Slugs sind unveränderlich. Wenn Sie einen anderen Slug benötigen, legen Sie eine neue Regel mit dem gewünschten Namen an und archivieren Sie die alte.
Reaktivieren
Archivierte Regeln lassen sich über den Archiv-Tab reaktivieren. Öffnen Sie den Tab unter /rules/archive, suchen Sie die Regel und wählen Sie Wiederherstellen im Kebab-Menü. Die Regel erscheint danach wieder in der aktiven Liste; ein neuer Entwurf oder eine neue Veröffentlichung ist anschließend möglich.
Der Archiv-Tab
Archivierte Regeln erreichen Sie über den Archiv-Tab am oberen Rand der Seite (/rules/archive).
Versionen
Versionshistorie
Wählen Sie Versionen ansehen im Kebab-Menü, um die Regeldetailseite zu öffnen, und wechseln Sie 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
Klicken Sie in der Zeile einer Version auf die Aktion Snapshot, um den Snapshot zu öffnen: die exakte .cgr-Datei und Spec, so wie sie zum Zeitpunkt der Veröffentlichung aussahen. Snapshots sind unveränderlich: Sie können sie lesen, aber nicht bearbeiten.
Diff zwischen Versionen
Öffnen Sie den Snapshot einer Version und klicken Sie auf Mit anderer Version vergleichen…, um die Vergleichsversion zu wählen. Die Diff-Ansicht stellt beide Versionen in drei Tabs nebeneinander dar: Quellcode (.cgr), Spezifikation (.spec.md) und Metadaten, und lässt Sie die Von- und Nach-Version jederzeit umstellen. So sehen Sie auf einen Blick, was sich zwischen zwei Releases geändert hat.
Prädikat-Katalog im Editor
Wenn Sie eine neue .cgr-Datei schreiben oder eine bestehende überarbeiten, 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üssen Sie den Katalog nicht auswendig kennen.
Katalog öffnen und filtern
Öffnen Sie 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 .cgr-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 |
SyntaxIssues |
SyntaxIssue |
Vor-analysierte Syntax-Pattern |
Die vollständige Property-Liste jedes Modell-Typs finden Sie unter Prädikat-Katalog.
Snippet-Palette
Die Snippet-Palette hält fertige DSL-Bausteine bereit, die Sie per Klick in den Editor einfügen. Sie ist in Kategorien gegliedert.
Palette öffnen
Klicken Sie in der Werkzeugleiste des Quellcode-Bereichs auf den Button Snippets (oder drücken Sie 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 Sie mit Tab springen und die Sie direkt ersetzen können.
Eigene Snippets
Das Portal speichert keine nutzerdefinierten Snippets. Wenn Sie häufig genutzte Muster wiederverwenden möchten, kopieren Sie den passenden DSL-Block aus einer bestehenden Regel in den Editor der neuen Regel und passen Sie ihn an.