codecharter analyze [path] [options]
[path] ist der Pfad zu einer .sln-, .slnx- oder .csproj-Datei. Wird er
weggelassen, durchsucht die CLI das Arbeitsverzeichnis rekursiv (ohne bin,
obj, .git und node_modules) und analysiert die am flachsten liegende
.sln/.slnx, ersatzweise eine .csproj, wenn keine Solution existiert.
Werden mehrere Kandidaten gefunden, wird der flachste, alphabetisch erste
genommen und die übrigen werden aufgelistet; mit einem Pfad lässt sich das
überschreiben. Wird nichts gefunden, bricht analyze mit Exit-Code 2 ab.
Beispiele
# Solution im aktuellen Verzeichnis automatisch finden
codecharter analyze
# Default-Lauf gegen eine explizite Solution, Output auf der Konsole
codecharter analyze MySolution.sln
# JSON-Output in eine Datei
codecharter analyze MySolution.sln --output json --output-file findings.json
# Nur Errors als Build-Blocker, GitHub-Annotations für PR-Inline-Kommentare
codecharter analyze MySolution.sln --output github-annotations --fail-on error
# Regelmenge aus einem anderen Verzeichnis
codecharter analyze MySolution.sln --rules ./shared-rules
# Nur Diff: nur auf den gegenüber dem Base-Branch geänderten Zeilen melden und gaten
codecharter analyze MySolution.sln --git-ref origin/main..HEAD --fail-on error
# Nur Diff aus einem vorab erzeugten Diff (oder stdin mit '-')
git diff origin/main..HEAD | codecharter analyze MySolution.sln --diff -
Optionen
| Option | Default | Beschreibung |
|---|---|---|
--rules <dir> |
./rules |
Verzeichnis mit .ccr-Regeln. Default ist ./rules im aktuellen Verzeichnis, mit Fallback auf die Beispiel-Regeln neben der CLI. |
--output <format> |
console |
Output-Format: console, json, sarif, github-annotations. Wiederholbar mit format:path für mehrere Ausgaben in einem Lauf. Siehe Output-Formate. |
--output-file <path> |
stdout | Output in eine Datei statt stdout schreiben. Gilt nur für die Einzel-Output-Form, nicht kombinierbar mit format:path. |
--severity <level> |
info |
Minimale Severity die im Output erscheint: info, warn, error. |
--fail-on <level> |
nicht gesetzt | Exit-Code 1 bei Findings ab dieser Severity: info, warn, error. Ohne dieses Flag führt jedes Finding, das die aktuelle --severity-Schwelle erreicht, zu Exit-Code 1. Mit --fail-on error wird nur bei Fehlern geblockt. |
--no-color |
aus | ANSI-Farbcodes im Konsolen-Output deaktivieren. |
--verbose |
aus | Detaillierte Diagnose-Logs. |
--progress |
aus | Live-Fortschritt auf stderr während der Analyse. Zeigt i/N plus Prozent pro Projekt und pro Regel; die Solution-Lade-Phase zeigt nur einen Spinner (kein messbarer Teilfortschritt). Im Terminal wird eine einzelne Spinner-Zeile aktualisiert, bei umgeleitetem stderr (wie in CI) werden gedrosselte Fortschrittszeilen ausgegeben. Kombinierbar mit --verbose. |
--workspace-root <path> |
nicht gesetzt | Pfad-Präfix, das aus Dateipfaden entfernt wird. Nützlich für github-annotations. |
--diff <path\|-> |
nicht gesetzt | Nur-Diff-Modus: nur Findings auf den von diesem Unified-Diff hinzugefügten oder geänderten Zeilen melden und gaten. Pfad zu einer Diff-Datei, oder - um den Diff von stdin zu lesen. Schließt --git-ref aus. |
--git-ref <range> |
nicht gesetzt | Nur-Diff-Modus: nur Findings auf den in dieser Git-Ref-Range geänderten Zeilen melden und gaten (z. B. origin/main..HEAD); führt git diff <range> --unified=0 aus. Schließt --diff aus. |
--write-baseline <file> |
nicht gesetzt | Analyse ausführen und die Fingerprints der aktuellen Findings in diese Baseline-Datei schreiben, dann mit 0 beenden, ohne Findings zu melden oder zu gaten. Siehe Baseline-Gate. |
--baseline <file> |
nicht gesetzt | Findings unterdrücken, die in dieser Baseline-Datei stehen, sodass Output und --fail-on nur für neue Findings gelten. Eine fehlende Datei analysiert alles (mit Warnung). Siehe Baseline-Gate. |
--telemetry |
aus | Opt-in: nach dem Lauf ein anonymes Nutzungs-Event (Tool-Name, Latenz-Bucket, Findings-Anzahl pro Regel, gehashte Workspace-ID) an den CodeCharter-Endpoint senden. Standardmäßig aus; kein Quellcode, keine Pfade, kein Code werden gesendet. Best-effort, beeinflusst den Lauf nie. |
--telemetry-endpoint <url> |
Portal | Den Telemetrie-Endpoint überschreiben. |
--license <path> |
nicht gesetzt | Pfad zur Lizenzdatei, überschreibt die Standard-Suchpfade. Jeder Lauf durchläuft die Lizenzprüfung. Siehe Lizenzdatei. |
Nur-Diff-Modus
--diff und --git-ref beschränken den Lauf auf Findings auf hinzugefügten oder geänderten Zeilen. Die gesamte Solution wird weiterhin geladen und analysiert (die Regeln brauchen das vollständige Typmodell), aber sowohl die gemeldeten Findings als auch das --fail-on-Gate beziehen sich nur auf den Diff. So scheitert ein Pull Request nur an Problemen, die er selbst einführt. Diff-Pfade werden gegen den Git-Repository-Root aufgelöst, damit auch eine Solution in einem Unterordner funktioniert. Berührt der Diff keine analysierte Zeile, meldet der Lauf nichts und endet mit 0.
Baseline-Gate
--baseline meldet und gatet nur Findings, die nicht in einer akzeptierten Baseline stehen; bestehende Findings werden geduldet, neue lassen den Build scheitern. Siehe den Baseline-Gate-Leitfaden. Kombinierbar mit dem Diff-Modus (beide Filter greifen).
Plattform-Profile
Deklariert die .codecharter/config.yml Ihres Repositorys Plattform-Profile, übernimmt analyze sie automatisch (die Datei wird gefunden, indem von der analysierten Datei aus nach oben gesucht wird) und führt dann nur noch die Portal-Regel-Bundles dieser Profile aus. Profile und lokale Regeln schließen sich gegenseitig aus, sie werden nicht kombiniert: Ein explizites --rules <dir> umgeht die Profile vollständig und hat immer Vorrang, ohne dieses Flag übernehmen konfigurierte Profile hingegen den Lauf, und ein lokales ./rules-Verzeichnis wird dann ignoriert (die CLI protokolliert, welche Quelle aktiv ist). Nur wenn keine Profile konfiguriert sind, kommt das gefundene Regel-Verzeichnis zum Einsatz (lokal ./rules, sonst der Bundled-Fallback). Siehe Plattform-Regeln verwenden. Läuft die Analyse nur mit eingebauten oder lokalen Regeln und ohne Plattform-Profile, gibt die CLI eine Deprecation-Warnung auf stderr aus, die auf Plattform-Profile verweist. Mit der Umgebungsvariable CODECHARTER_SUPPRESS_DEPRECATION_WARNING=1 lässt sich die Warnung unterdrücken (der Wert muss genau 1 sein); auf Findings und Exit-Code hat die Warnung keinen Einfluss.
Suppressions
Die Abschnitte ignore und exclude in .codecharter/config.yml sowie // codecharter-disable- und // codecharter-disable-next-line-Kommentare im Quellcode unterdrücken Findings vor Output und Gating. Unterdrückte Findings erscheinen also weder in den Ergebnissen noch beeinflussen sie den Exit-Code. Siehe Suppressions.
Exit-Codes
0: Lauf erfolgreich, keine Findings ab der aktiven Schwelle.1: Ein oder mehrere Findings ab der Schwelle. Ohne--fail-onlöst jedes Finding ab der--severity-Schwelle Exit-Code 1 aus.2: Konfigurations- oder Regel-Fehler.3: Analyse fehlgeschlagen, etwa weil die Solution oder ein Projekt nicht geladen werden konnte.6: Lizenzfehler (fehlend, abgelaufen oder für diese CLI-Version nicht gültig).
Mit konfigurierten Plattform-Profilen kann die Vorprüfung außerdem mit 2 (Lockfile fehlt), 3 (Profil-Cache unvollständig und Portal nicht erreichbar) oder 4 (Lockfile veraltet) enden. Mehr unter Exit-Codes.