Findings und Severities

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

Anatomie eines Findings

Jedes Finding hat:

Im JSON-Output:

{
  "rule": "DateTime-Direct-Usage",
  "severity": "warn",
  "category": "Testability",
  "file": "src/Domain/PricingEngine.cs",
  "line": 42,
  "column": 18,
  "message": "Direct call to DateTime.UtcNow",
  "recommendation": "Inject TimeProvider via constructor and call GetUtcNow()"
}

Severities

CodeGuard kennt drei Stufen.

info

Hinweis. Hat keinen Build-blockierenden Charakter. 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 nicht, aber sie ist sichtbar im Output und im Editor. Gut für Konventionen die ihr durchsetzen wollt, aber nicht hart blockieren, etwa Async-Methoden ohne CancellationToken. Mit --fail-on warn wird sie zur Build-Bremse.

error

Fehler. Per Default Build-blockierend wenn ihr --fail-on error setzt (das ist die Empfehlung für CI). Reserviert für Verstöße die wirklich nicht in den Main-Branch dürfen, kaputte Architektur, Sicherheitslücken, explizit verbotene APIs.

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 wir kollektiv durchsetzen wollen, 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 // codeguard:disable statt zu fixen.

Severities pro Stelle überschreiben

In .codeguard/severity.cfg:

# Sehen wir nicht als Build-Blocker, in dem Repo
DateTime-Direct-Usage = warn

# In dem Repo besonders streng
Cognitive-Complexity = error

So könnt ihr eingebaute Regeln pro Repo nach euren Maßstäben hoch- oder runterstufen.

Aggregation

Im Build-Output stehen die Findings sortiert nach Severity, dann Datei, dann Zeile. Am Ende des Runs gibt es eine Summary:

Done in 28.4s. 17 findings (3 errors, 14 warnings, 0 infos)

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