Baseline gate

The baseline gate lets CodeCharter fail a build only on new findings while tolerating a known set of pre-existing ones. It is the natural fit for adopting CodeCharter on an existing codebase: accept today's findings as a baseline, then keep new ones from sneaking in.

How it differs from diff mode

• Diff mode (--diff / --git-ref) scopes to the lines a change touched — "new in this PR, by line".
• Baseline mode (--baseline) scopes to findings not in an accepted snapshot — "new versus the baseline, by identity". It catches a new finding even on a line the PR did not touch.

The two compose: with both set, a finding must be on a changed line and not in the baseline to be reported.

Fingerprints

Each finding gets a stable fingerprint derived from its identity (rule, entity kind, entity name, category), its file path (repository-relative when --workspace-root is set), and an occurrence counter that keeps repeated findings of the same kind in one file distinguishable. It is independent of line numbers, so it survives line shifts and reformatting. Moving the file or renaming the entity changes the fingerprint, so the finding then looks new — regenerate the baseline to re-accept it. The fingerprint is also emitted in JSON output and as SARIF partialFingerprints.

Workflow

# 1. Accept the current findings as the baseline and commit it.
codecharter analyze MySolution.sln --write-baseline .codecharter/baseline.json
git add .codecharter/baseline.json && git commit -m "chore: codecharter baseline"

# 2. In CI, gate only on new findings.
codecharter analyze MySolution.sln --baseline .codecharter/baseline.json --fail-on error

• Generate the baseline with the same options you gate with (rules, --severity), so the recorded set matches what is later evaluated.
• Pass --workspace-root <repo root> (or run from the repo root) when generating and gating, so fingerprints use repository-relative paths and the baseline is portable across machines and CI. The GitHub Action sets this for you.
• The baseline file is deterministic (sorted, no timestamps), so it diffs cleanly in version control.
• To accept newly introduced findings (or prune resolved ones), regenerate the file with --write-baseline and commit it.

Behavior notes

• A missing --baseline file analyzes everything and prints a warning — it does not silently pass. (Useful before the first baseline is committed.)
• A corrupt or unsupported-version baseline file is a hard error (exit 2).
• --write-baseline only records and exits 0; it never reports findings or trips --fail-on.
• --write-baseline always records the full (severity-filtered) analysis result: combined with --diff/--git-ref, the written baseline is not diff-scoped.