Ein Regelverzeichnis läuft, wenn es unter rules: in
.codecharter/config.yml deklariert ist (codecharter config add rules rules),
aufgelöst gegen den Repository-Root, oder mit --rules <dir> übergeben wird.
Ein Ordner wird nie aufgenommen, nur weil er existiert.
Deklarierte Verzeichnisse laufen zusätzlich zu den
Plattform-Profilen aus derselben Datei:
zuerst die Profile, dann die rules:-Verzeichnisse, dann jedes
--rules-Verzeichnis. Bei doppelter Regel-ID gewinnt die spätere Quelle, und
der Lauf nennt jede überdeckte ID. Das Layout unten gilt für jedes
Regelverzeichnis im Repo, egal ob ihr es deklariert, mit --rules übergebt
oder in ein Profil bündelt.
Empfohlenes Layout im Repo
rules/
├── architecture/
│ ├── domain-must-not-reference-web.ccr
│ └── repository-naming.ccr
├── naming/
│ ├── no-manager-suffix.ccr
│ ├── no-manager-suffix.spec.md
│ └── async-suffix.ccr
└── team-conventions/
└── controller-action-limit.ccr
.codecharter/config.yml
Unterverzeichnisse unter rules/ sind frei wählbar. CodeCharter liest
rekursiv alle .ccr-Dateien. Ältere .cgr-Dateien aus der Zeit vor der
Umbenennung von CodeGuard zu CodeCharter werden zur Abwärtskompatibilität
weiterhin gelesen, damit bestehende Repositories nicht angepasst werden müssen.
Die Regel-ID ist der Dateiname ohne die Endung .ccr; die Namen der
Unterverzeichnisse haben keine Bedeutung. Diese IDs werden in
.codecharter/config.yml-Einträgen und Suppression-Kommentaren referenziert.
Vermeidet deshalb gleiche Dateinamen in verschiedenen Ordnern.
Spec-Tests liegen als <regel-name>.spec.md neben der .ccr-Datei und
werden von codecharter test rekursiv gefunden.
rules/ initialisieren
codecharter init
Legt ein rules/-Verzeichnis mit zwei Beispiel-Regeln an, von dem aus ihr
weiter wachsen könnt.
.codecharter/config.yml
Die Repository-Konfiguration liegt unter .codecharter/config.yml. Neben anderen
Abschnitten schaltet ignore Regeln ab (optional auf einen Namespace oder
passende Entity-Namen beschränkt), und exclude nimmt ganze Pfade aus der
Analyse:
version: 1
ignore:
- rule: namespace-distance
in: Acme.Generated
- rule: async-suffix
exclude:
- "**/tests/**"
- "**/obj/**"
Den vollständigen Satz an Abschnitten (Profile, Parameter, Severities, Regel-Aktivierung und Pfad-Scopes) findet ihr unter Konfigurationsdatei.
Inline-Suppressions
Pro Stelle im Code:
// codecharter-disable-next-line datetime-direct-usage
var migrationTimestamp = DateTime.UtcNow;
Die Regel-ID im Kommentar muss exakt dem Dateinamen der Regel entsprechen, inklusive Groß- und Kleinschreibung. Siehe Suppressions für alle Varianten.
Plattform-Profile im Repo
Wenn ihr Plattform-Profile nutzt, listet ihr sie in .codecharter/config.yml;
codecharter.lock.json (pinnt jedes Profil über einen Content-Hash) und die
heruntergeladenen Regel-Bundles liegen beide unter .codecharter/:
.codecharter/
├── config.yml
├── codecharter.lock.json
└── cache/
Committet config.yml und codecharter.lock.json; cache/ ist ein
lokaler Download-Cache und gehört nicht in die Versionsverwaltung (siehe
Konfigurationsdatei).
Multi-Repo und Monorepo
In einem Monorepo könnt ihr rules/-Verzeichnisse pro Sub-Projekt haben
und über --rules darauf zeigen. CodeCharter findet .codecharter/config.yml,
indem es von der analysierten Datei aufwärts sucht; eine Konfiguration im
Repository-Wurzelverzeichnis gilt damit für alles darunter.