Solution oder Projekt mit der CodeCharter-CLI analysieren

codecharter analyze [path] [options]

[path] ist der Pfad zu einer .sln-, .slnx- oder .csproj-Datei. Wird er weggelassen, oder zeigt er auf ein bestehendes Verzeichnis, durchsucht die CLI dieses Verzeichnis rekursiv (ohne Angabe das Arbeitsverzeichnis; 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 dem Pfad zu einer konkreten Datei 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

# Ein Regelverzeichnis zu den Quellen der Config hinzufügen
codecharter analyze MySolution.sln --rules ./shared-rules

# Nur die genannten Verzeichnisse ausführen, ohne die Quellen der Config
codecharter analyze MySolution.sln --rules ./shared-rules --rules-only

# 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>	nicht gesetzt	Verzeichnis mit .ccr- oder .cgr-Regeldateien, relativ zum aktuellen Verzeichnis. Mehrfach angebbar. Läuft zusätzlich zu den Quellen, die .codecharter/config.yml deklariert. Siehe Regelquellen.
--rules-only	aus	Nur die --rules-Verzeichnisse ausführen und die in der Config deklarierten profiles: und rules: ignorieren. Braucht mindestens ein --rules.
--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 <dir>	nicht gesetzt	Läuft, als wäre der Befehl in diesem Workspace gestartet worden, wie git -C. Eine Datei verankert ihr Verzeichnis. Global: jeder workspace-gebundene Befehl nimmt die Option. Siehe Workspace angeben.
--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. Eine Zwei-Punkt-Range wird ab dem Merge-Base gebildet, eine ausdrücklich angegebene Drei-Punkt-Range wird so verwendet wie geschrieben, und eine einzelne Ref oder SHA behält Gits Bedeutung „Arbeitsverzeichnis gegen diesen Commit“. Schließt --diff aus.
--diff-context	aus	Mit --diff/--git-ref zusätzlich Findings in den berührten Dateien melden, deren Zeile nicht zu den geänderten Zeilen gehört, etwa eine neu entstandene God-Class. Sie zählen dann zu den gemeldeten Findings und zum --fail-on-Gate. Ohne das Flag werden sie nur auf stderr gezählt.
--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.

Workspace angeben

Jeder Befehl, der auf einem Workspace arbeitet (analyze, graph, coverage, baseline, config, restore, update, req und die übrigen), nimmt die globale Option --workspace <dir>. Der Befehl läuft dann, als wäre er in diesem Verzeichnis gestartet worden, so wie git -C <dir>: Config-Suche, Lockfile, relative Pfade und --rules-Verzeichnisse lösen sich innerhalb des Workspace auf, das Verzeichnis deiner Shell bleibt unberührt. Ein Pfad zu einer Datei verankert deren Verzeichnis; ein Pfad, der nicht existiert, ist ein Aufruffehler.

Nimmt ein Befehl zusätzlich einen eigenen Pfad, werden die expliziten Angaben kombiniert und nie stillschweigend überschrieben:

• Ein relativer Pfad wird innerhalb des Workspace aufgelöst, codecharter analyze src/App.sln --workspace ../worktree analysiert also ../worktree/src/App.sln.
• Ein absoluter Pfad innerhalb des Workspace wird so verwendet, wie er angegeben ist.
• Ein absoluter Pfad außerhalb des Workspace ist ein Widerspruch: Der Befehl bricht mit einem Aufruffehler ab, der beide Werte nennt, bevor er irgendetwas tut. Lass eine der beiden Angaben weg oder gib den Pfad relativ zum Workspace an.

Ohne --workspace nutzt jeder Befehl wie bisher das aktuelle Verzeichnis. Agenten, die in einem Git-Worktree arbeiten, sollten --workspace übergeben (oder bei den MCP-Tools den Anker, siehe Workspace-Anker), damit sie nie versehentlich den Haupt-Checkout bearbeiten.

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. Ohne Pfad-Argument analysiert der Lauf die Solution, die jedes vom Diff berührte Projekt enthält, also dieselbe Einheit, die das MCP-Tool analyze_diff wählt. Ein Repository mit mehreren Solutions nebeneinander braucht für einen Diff-Lauf daher keinen Pfad. Berührt der Diff keine analysierte Zeile, meldet der Lauf nichts und endet mit 0.

--git-ref bildet eine Zwei-Punkt-Range wie origin/main..HEAD ab dem Merge-Base der beiden Commits, also in Gits Drei-Punkt-Form. Commits, die seit dem Abzweigen auf dem Base-Branch gelandet sind, zählen damit nicht als deine Änderungen. Schreibst du die Drei-Punkt-Form ausdrücklich hin, wird sie so verwendet wie geschrieben; eine einzelne Ref oder SHA behält Gits eigene Bedeutung „Arbeitsverzeichnis gegen diesen Commit“. coverage --git-ref verwendet dieselbe Bereichssyntax.

Manche Findings hängen an einer Zeile, die dein Diff gar nicht berührt hat, obwohl deine Änderung sie ausgelöst hat, etwa eine Klasse, die erst durch deine neue Methode zur God-Class wurde. Der Nur-Diff-Modus zählt sie auf stderr, statt sie zu verschweigen; mit --diff-context werden sie gemeldet und zählen zum --fail-on-Gate.

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).

Regelquellen

Ein Lauf wertet genau die deklarierten Regelquellen aus, in dieser Reihenfolge:

1. Die Plattform-Profile unter profiles: in .codecharter/config.yml, in der Reihenfolge der Config (die Datei wird gefunden, indem von der analysierten Datei aus nach oben gesucht wird). Siehe Plattform-Profile nutzen.
2. Die Regelverzeichnisse unter rules: in derselben Datei, aufgelöst gegen das Repository-Root. Ein Pfad, der das Repository verlässt, wird abgelehnt.
3. Jedes --rules <dir>, aufgelöst gegen das aktuelle Verzeichnis.

Die Quellen addieren sich. Definieren zwei Quellen dieselbe Regel-ID, gewinnt die spätere, und der Lauf nennt jede überdeckte ID. --rules-only lässt die ersten beiden Gruppen weg und führt nur die --rules-Verzeichnisse aus, so wie sich --rules vor 1.6.4 verhalten hat.

Nichts wird stillschweigend aufgenommen: Ein rules-Ordner, der existiert, aber nicht deklariert ist, wird nie gelesen (der Lauf nennt ihn und den rules:-Eintrag, der ihn deklarieren würde), und die mit der CLI ausgelieferten Beispielregeln werden nur geladen, wenn ihr sie nennt. Ein Lauf ganz ohne Regelquelle bricht mit Exit-Code 2 ab und sagt, wie ihr eine deklariert: codecharter config init, danach codecharter config add profiles codeguard/csharp-all@^1.2 oder codecharter config add rules <dir>. Ein deklariertes Verzeichnis, das fehlt oder keine Regeln enthält, wird mit Namen gemeldet.

Die Rules:-Zeile auf stderr listet jede Quelle mit den Regeln, die sie nach dem Überdecken beiträgt, und nennt die überdeckten getrennt, zum Beispiel Rules: 245 from codeguard/csharp-all@1.2.0 (2 shadowed), 7 from .codecharter/rules. Die Zahlen ergeben zusammen die Regeln, die der Lauf zusammengesetzt hat.

Laufkontext und Reichweite

Jeder Lauf sagt, was er tatsächlich geprüft hat. Der JSON-Report enthält das als run, der SARIF-Report als runs[0].properties.run und jedes MCP-Ergebnis von analyze_* und graph_* als run, jeweils in derselben Form:

• analysisUnit, analysisUnitKind (solution oder project), configPath und lockfilePath. Jeder Pfad im Laufkontext ist relativ zum Repository-Root (dem Verzeichnis mit .codecharter/config.yml) und nutzt Schrägstriche, zum Beispiel src/App.sln und .codecharter/config.yml. Ein Pfad außerhalb des Repositorys, oder jeder Pfad in einem Lauf ohne Config, steht nur als Dateiname da. Der Laufkontext enthält nie einen absoluten Pfad, weil JSON- und SARIF-Reports in Code Scanning hochgeladen und als CI-Artefakte aufbewahrt werden. Konsole und stderr dürfen weiterhin absolute Pfade zeigen.
• ruleSources: ein Eintrag je deklarierter Quelle mit kind, identity (bei einem Profil das aufgelöste slug@version), declaredIdentity (wie in der Config oder auf der Kommandozeile angegeben), configuredCount (was das Lockfile für ein Profil festschreibt, bei einem rules:-Verzeichnis die Zahl seiner Regeldateien, null wenn unbekannt), resolvedCount, shadowedCount, isResolved und, bei einer Quelle ohne Beitrag, unresolvedReason.
• reach: die Regelanzahlen configured, resolved und evaluated, unresolvedSources, drift (jede Abweichung zwischen den Profilen der Config und dem Lockfile), coreLibraryUnresolvedProjects, projectLoadFailures (jedes Projekt der Analyseeinheit, das nicht geladen werden konnte, mit der von MSBuild gemeldeten Ursache), isInconclusive und inconclusiveReasons.

Ein Lauf ist nicht aussagekräftig (inconclusive), sobald einer dieser Gründe zutrifft:

Code	Bedeutung	Nächster Schritt
no-rule-source	Keine Regelquelle konfiguriert.	Eine deklarieren, siehe Regelquellen.
nothing-evaluated	Keine einzige Regel wurde ausgewertet.	Regelquellen und die Meldungen zu übersprungenen Regeln prüfen.
resolved-short-of-configured	Ein Profil hat weniger Regeln aufgelöst, als sein Lockfile-Eintrag festschreibt, oder ein rules:-Verzeichnis hat weniger Regeln geladen, als es Regeldateien enthält.	codecharter restore oder die genannten Regeldateien korrigieren
resolved-beyond-configured	Ein Profil hat mehr Regeln aufgelöst, als sein Lockfile-Eintrag festschreibt.	codecharter update, danach codecharter restore
source-unresolved	Eine deklarierte Quelle hat keine Regeln beigetragen.	Die genannte Quelle korrigieren.
lockfile-missing	Profile sind deklariert, aber es gibt kein Lockfile.	codecharter update
config-lock-drift	Die Profile der Config weichen vom Lockfile des Laufs ab.	codecharter update
core-library-unresolved	Ein Projekt konnte seine eigene Core-Library nicht auflösen, seine Fakten können falsch sein.	dotnet restore
project-load-failed	Ein Projekt der Analyseeinheit konnte nicht geladen werden, sein Code ist nicht Teil des Laufs. Findings der übrigen Projekte werden weiterhin gemeldet.	Die in projectLoadFailures genannte Ursache beheben

Ein nicht aussagekräftiger Lauf endet mit Exit-Code 2, egal was er gefunden hat, und schreibt je Grund eine Zeile auf stderr:

Inconclusive run: 1 rules evaluated, 1 resolved. This is NOT a clean result.
  [core-library-unresolved] 1 project(s) could not resolve their own core library reference (Tiny), so every fact extracted from them may be wrong; run 'dotnet restore'.

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-on löst jedes Finding ab der --severity-Schwelle Exit-Code 1 aus.
• 2: Aufruf- oder Konfigurationsfehler (zum Beispiel ungültige Flag-Kombinationen, eine fehlende Diff-Datei, keine konfigurierte Regelquelle, ein --rules-Verzeichnis, das nicht existiert, oder eine defekte Baseline-Datei) oder ein nicht aussagekräftiger Lauf (siehe Laufkontext und Reichweite). Ein solcher Lauf endet auch dann mit 2, wenn er Verstöße gefunden hat.
• 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.