Findings und Severities

Ein Finding ist die kleinste Einheit Output von CodeCharter. Eine konkrete Stelle im Code an der eine konkrete Regel zugeschlagen hat.

Anatomie eines Findings

Jedes Finding hat:

Feld	Inhalt
Rule	Slug und Anzeigename der Regel, z.B. datetime-direct-usage
Severity	info, warn oder error (maschinenlesbarer Output schreibt die mittlere Stufe als warning)
Category	Frei wählbar, gruppiert zusammengehörige Regeln
Entity	Name und Art (Klasse, Methode, ...) des Code-Elements, das die Regel getroffen hat
File	Absoluter oder relativer Pfad zur Datei
Line	Zeilennummer
Column	optional, Spaltennummer
Message	Was hier konkret gefunden wurde
Description	Was die Regel prüft (aus @description der Regel)
Recommendation	Was zu tun ist (aus @recommendation der Regel)
Fingerprint	Stabile, zeilenunabhängige ID des Findings über Läufe hinweg; wird von --baseline genutzt, um bekannte Findings zu unterdrücken (siehe Baseline)

Im JSON-Output erscheinen Findings als violations neben einem summary-Block:

{
  "summary": {
    "totalViolations": 1,
    "totalTypes": 128,
    "totalMethods": 932,
    "durationMs": 28400
  },
  "violations": [
    {
      "ruleId": "datetime-direct-usage",
      "ruleName": "Direct DateTime/DateTimeOffset usage instead of TimeProvider",
      "severity": "warning",
      "category": "Testability",
      "entityName": "PricingEngine.CalculatePrice",
      "entityKind": "Method",
      "filePath": "src/Domain/PricingEngine.cs",
      "lineNumber": 42,
      "column": 18,
      "message": "Direct call to DateTime.UtcNow",
      "description": "Direct calls to DateTime.Now/UtcNow/Today make code untestable",
      "recommendation": "Inject TimeProvider via constructor and call GetUtcNow()",
      "fingerprint": "a1b2c3d4..."
    }
  ]
}

Severities

CodeCharter kennt drei Stufen.

info

Hinweis. Lässt wie jedes Finding den Build per Default fehlschlagen; mit --fail-on warn oder --fail-on error nehmen Sie info-Findings aus dem Build-Gate heraus. Gut für Regeln die nice-to-haves erwischen: "diese Stelle wäre einfacher lesbar mit folgender Refactoring-Idee". Sollten in der täglichen Arbeit nicht zu viele werden, sonst werden sie ignoriert.

warn

Warnung. Per Default blockiert sie den Build wie jedes andere Finding und ist sichtbar im Output und im Editor. Gut für Konventionen, die Sie kollektiv durchsetzen möchten, etwa Async-Methoden ohne CancellationToken. Mit --fail-on warn greift das Build-Gate nur noch bei warn und error, info-Findings werden durchgelassen.

error

Fehler. Reserviert für Verstöße, die wirklich nicht in den Main-Branch dürfen: kaputte Architektur, Sicherheitslücken, explizit verbotene APIs.

Standard-Verhalten ohne --fail-on: Ohne dieses Flag verursacht jedes Finding jeder Severity (auch warn und info) Exit-Code 1. Exit-Code 0 bedeutet: keine Findings auf oder über dem aktiven Schwellwert. Mit --fail-on warn werden nur info-Findings durchgelassen, mit --fail-on error passieren sowohl info als auch warn ohne den Build zu blockieren.

Wann welche Severity

Faustregel: so streng wie nötig, so freundlich wie möglich.

• error nur wenn der Verstoß einen echten Schaden anrichten würde (Sicherheit, Stabilität, Vertragsbruch).
• warn für Konventionen, die das Team kollektiv durchsetzen möchte, mit dem Verständnis, dass es auch begründete Ausnahmen gibt.
• info für Stil-Empfehlungen die "wäre besser, aber okay so".

Eine Regel die nur error produziert weil "wenn wir schon eine Regel schreiben, soll sie auch was bewirken" ist ein Anti-Pattern. Innerhalb weniger Tage suchen die Devs nach // codecharter-disable statt zu fixen.

Severity einer Regel überschreiben

Die Severity einer Regel ändern Sie in .codecharter/config.yml unter overrides:, und eine Regel schalten Sie unter ignore: ganz ab. Beides wird pro Regel über den Slug adressiert, nicht pro Datei oder pro Zeile. Siehe Konfigurationsdatei für alle verfügbaren Abschnitte.

# .codecharter/config.yml
version: 1
overrides:
  datetime-direct-usage:     # Slug einer eingebauten Regel
    severity: warning        # error | warning | info
ignore:
  - rule: empty-catch-block  # diese Regel komplett abschalten

Um Findings an einer bestimmten Stelle zu unterdrücken, verwenden Sie stattdessen einen // codecharter-disable-Kommentar (siehe Suppressions).

Aggregation

Im Build-Output stehen die Findings sortiert nach Severity, dann Datei, dann Zeile. Doppelte Findings (gleiche Regel, Entity, Datei und Zeile) werden nur einmal gemeldet. Mit --severity <level> legen Sie die minimale Severity fest, die angezeigt wird (Default: info, also alles). Am Ende des Runs gibt es eine Summary; Severity-Stufen ohne Findings werden weggelassen:

  17 violations (3 errors, 14 warnings)
  Analyzed 128 types, 932 methods in 28.4s

Exit-Code-Verhalten und CI-Integration siehe Exit-Codes und Output-Formate.