Auf der Regeln-Seite unter /rules erstellen, bearbeiten, veröffentlichen und archivieren Sie die eigenen Regeln Ihrer Organisation und durchsuchen den eingebauten Plattform-Regelkatalog nach Regeln zur Wiederverwendung. Die Seite hat zwei Tabs: Meine für die Regeln Ihrer 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 Ihrer Organisation als Karten, jede mit Name, Slug, Kategorie, Schweregrad und Status. Der Tab Beispiele zeigt dieselbe Katalogansicht über CodeCharters kuratierte eingebaute Regeln, die Sie durchsuchen und in Ihre eigenen Regeln übernehmen können. Wie Sie den Katalog durchsuchen und übernehmen, 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 Sie die Ergebnisse eingrenzen.
Im Tab Meine kommt zusätzlich ein Status-Filter hinzu (Alle, Entwurf, Veröffentlicht, Archiviert); stellen Sie 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
Klicken Sie im Tab Meine 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 duplizieren oder übernehmen
Statt eine Regel von Grund auf neu zu schreiben, klicken Sie auf Duplizieren bei einer eigenen Regelkarte im Tab Meine oder auf Ü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 finden Sie unter Der Regelkatalog.
Regel editieren
Klicken Sie im Tab Meine auf einer Regelkarte auf 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. 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, und 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 matcht, ä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. Speichern Sie 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, 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>.ccr 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.
Entwurf ans Portal senden
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 Veröffentlichen weiter unten). Nach einem erfolgreichen Push können Sie in VS Code weiterarbeiten und den Entwurf erneut übertragen.
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.
Veröffentlichen
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.
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. 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 Regel 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 Regel-Referenz. Diese Profilentwürfe prüfen und veröffentlichen Sie anschließend wie gewohnt. Das ist der übliche Weg, um eine neue Regel-Version in die CI-Pipelines zu bringen.
Archivieren
Öffnen Sie die Detailseite der Regel (Button Details auf ihrer Karte) und klicken Sie auf 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 finden Sie sie wieder. Hat die Regel einen offenen Entwurf, ist das Archivieren blockiert, bis Sie diesen Entwurf veröffentlicht oder verworfen haben.
Slugs sind unveränderlich. Wenn Sie einen anderen Slug benötigen, kopieren Sie die Regel mit Duplizieren unter dem neuen Slug und archivieren Sie die alte, das übernimmt auch Quelltext und Spec, sodass Sie nicht bei null anfangen.
Reaktivieren
Das Archivieren ist vollständig reversibel. Öffnen Sie die Detailseite der archivierten Regel und klicken Sie auf 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
Öffnen Sie die Detailseite einer Regel (Button Details auf ihrer Karte) 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 .ccr-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 (.ccr), 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 .ccr-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 .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 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. Um eine ganze Regel wiederzuverwenden, nutzen Sie stattdessen Duplizieren (siehe "Regel duplizieren oder übernehmen" oben); für ein kleineres Muster kopieren Sie den passenden DSL-Block aus einer bestehenden Regel in den Editor der neuen Regel und passen Sie ihn an.