Konfigurationsdatei

CodeCharter liest eine einzige Konfigurationsdatei, .codecharter/config.yml, aus Ihrem Repository. Sie steuert, welche Regel-Profile gelten, die Werte einstellbarer Regel-Parameter, die Severity je Regel, welche Findings ein- oder ausgeschaltet sind und welche Pfade analysiert werden. Eine Datei deckt das gesamte Repository ab, und mit Pfad-scopes variieren Sie die Konfiguration für einzelne Ordner.

Ablage und Auffinden

Legen Sie die Datei unter .codecharter/config.yml im Repository ab. Wenn CodeCharter eine Datei analysiert, sucht es .codecharter/config.yml ausgehend vom Verzeichnis der Datei aufwärts bis zur Repository-Wurzel. Eine Konfiguration im Wurzelverzeichnis gilt damit für alles darunter.

Daneben gibt es optional .codecharter/config.local.yml für persönliche, maschinenlokale Überschreibungen. Diese Datei wird nie eingecheckt (nehmen Sie sie in .gitignore auf) und hat Vorrang vor config.yml. Nutzen Sie sie, um lokal Ihre Regelversionen mitlaufen zu lassen oder eine Regel auf Ihrem Rechner leiser zu stellen, ohne die geteilte Konfiguration zu ändern. Die CI, die diese Datei nie sieht, bleibt reproduzierbar.

Ein vollständiges Beispiel

version: 1

# Anzuwendende Regel-Profile, neueste zuerst. Ein blanker Slug oder @latest
# folgt der neuesten veröffentlichten Version, eine exakte Version pinnt sie.
# Plattform-Profile nutzen die Form org/slug. Mit { path: ... } laden Sie ein
# lokales Bundle statt vom Portal.
profiles:
  - [email protected]
  - security@latest
  - acme/house-style@^2.1.0
  - { path: ./bundles/internal-rules.cgbundle }

# Werte für einstellbare Regel-Parameter, adressiert über rule-slug.paramName.
params:
  cyclomatic-complexity.max: "15"
  method-length.maxLines: "60"

# Severity je Regel. Hier lässt sich ausschließlich die Severity überschreiben.
overrides:
  magic-number:
    severity: warning
  empty-catch-block:
    severity: error

# Findings ausschalten. Optional auf einen Namespace (in:) oder auf Entities
# beschränken, deren Name einem Glob entspricht (match:).
ignore:
  - rule: namespace-distance
    in: Acme.Generated
  - rule: todo-comment
  - rule: const-naming
    match: "*InstanceMemberBindingFlags"

# Eine Regel wieder einschalten, nachdem sie breiter ignoriert wurde (z. B. in
# einem Scope).
include:
  - rule: todo-comment

# Pfade, die vollständig von der Analyse ausgeschlossen werden (Glob-Muster).
exclude:
  - "**/tests/**"
  - "**/obj/**"
  - "**/Migrations/**"

# Ordnerspezifische Überschreibungen. Jeder Scope matcht ein oder mehrere
# Pfad-Globs und kann jeden der obigen Abschnitte setzen. Die Einstellungen
# gelten nur für Dateien, die der Scope matcht.
scopes:
  - match:
      - "src/Legacy/**"
    overrides:
      magic-number:
        severity: info
    ignore:
      - rule: cyclomatic-complexity

Abschnitte

version

Pflicht. Die Version des Konfigurationsformats. Verwenden Sie version: 1.

profiles

Die anzuwendenden Regel-Profile. Jeder Eintrag ist entweder eine Slug-Referenz oder ein lokaler Bundle-Pfad:

• [email protected], eine exakte veröffentlichte Version.
• security@latest oder ein blankes security, folgt der neuesten veröffentlichten Version und wird bei codecharter update neu aufgelöst.
• security@^2.1.0 oder [email protected].*, ein Versionsbereich.
• acme/[email protected], ein Plattform-Profil in der Form org/slug.
• { path: ./bundles/rules.cgbundle }, ein lokales .cgbundle, das nicht vom Portal geladen wird.

params

Werte für Parameter, die eine Regel anbietet, adressiert über rule-slug.paramName. Werte werden als Zeichenketten geschrieben; CodeCharter prüft sie gegen den deklarierten Typ und Wertebereich des Parameters. Eine Regel ohne Parameter oder ein nicht existierender Parametername wird von codecharter config validate gemeldet.

overrides

Ändert die Severity einer Regel. Das einzige Feld ist severity, eines von error, warning (oder warn) oder info. Um eine Regel ganz abzuschalten, verwenden Sie ignore statt overrides.

ignore und include

ignore schaltet Findings aus, include schaltet sie wieder ein. Jeder Eintrag adressiert eine Regel per Slug und kann das Ziel eingrenzen:

• in: Acme.Core, gilt nur für Findings in diesem Namespace oder einem darunterliegenden.
• match: "*Dto", gilt nur für Entities, deren Name dem Glob entspricht.

ignore und include teilen sich ein Aktivierungssignal, das der Reihe nach ausgewertet wird: zuerst die Basis-Ebene, dann jeder passende Scope von oben nach unten. Der letzte passende Eintrag gewinnt. So können Sie eine Regel breit ignorieren und für einen engeren Pfad oder Namespace wieder einschalten.

exclude

Glob-Muster für Pfade, die vor jeder Regelauswertung aus der Analyse fallen. exclude ist additiv: die Basis-Muster und die Muster jedes passenden Scopes gelten zusammen.

scopes

Ordnerspezifische Konfiguration. Jeder Scope hat eine match-Liste aus Pfad-Globs und kann jeden der Abschnitte params, overrides, ignore, include und exclude enthalten. Die Einstellungen eines Scopes gelten nur für Dateien, die er matcht. Die Auflösung erfolgt nach dem Prinzip letzter Treffer gewinnt für params, overrides und die Regel-Aktivierung, verankert an der Quelldatei der ausgewerteten Entität; exclude ist additiv über alle passenden Scopes.

Konfiguration prüfen und inspizieren

Drei Befehle helfen Ihnen beim Arbeiten mit der Datei:

• codecharter config explain <pfad> zeigt die effektive Konfiguration für eine bestimmte Quelldatei, einschließlich der Ebene (Basis oder welcher Scope), aus der jeder Wert stammt. Mit --json erhalten Sie maschinenlesbare Ausgabe.
• codecharter config validate prüft die Datei auf strukturelle Fehler, unbekannte Regel-Ids, ungültige Parameterwerte und Einträge, die nie greifen.
• codecharter config schema gibt ein JSON-Schema für .codecharter/config.yml aus, das Editoren für Vervollständigung und Validierung nutzen können. Mit --out <datei> schreiben Sie es auf die Festplatte.

Um die Datei über die Kommandozeile zu bearbeiten statt von Hand (Parameter und Severities setzen, Profile und Ausschlüsse verwalten, die Datei anlegen und das lokale Overlay synchronisieren), nutzen Sie die config-Schreibbefehle. Jede Bearbeitung erhält Ihre Kommentare und Formatierung und wird vor dem Schreiben geprüft. Siehe codecharter config.

Verhältnis zu Suppressions

ignore und exclude wirken auf Repository- oder Ordner-Ebene. Um ein einzelnes Finding genau an der Stelle im Code zu unterdrücken, an der es auftritt, verwenden Sie stattdessen einen Inline-Suppression-Kommentar, siehe Suppressions.