Skip to content

Determinism

Why the same input always produces the same findings in CodeCharter.

Updated on 2026-07-13

CodeCharter guarantees: the same source code state, the same rule set, the same CodeCharter version, and the same analysis options will always produce exactly the same findings, regardless of machine, time of day, system load, or locale settings.

This guarantee is structural, not best-effort: the analysis is stateless, so it never depends on wall-clock time, random values, or filesystem ordering. The same input always maps to the same output, every output format reports the same findings, and the rule-package schema stays stable across patch releases so custom rules keep working.

What Can Change the Output

If any of these change, the findings can change:

  1. The source code changes. This includes .codecharter/config.yml and inline suppression comments (// codecharter-disable), which travel with the source and also affect what is reported.
  2. The rule set changes. A .ccr file is added, removed, or modified; a profile in .codecharter/config.yml is changed; codecharter.lock.json is updated to a new resolution; or a rule's severity override or ignore entry is edited.
  3. The CodeCharter version changes. New versions may refine built-in rules or add new schema properties.
  4. The analysis options change. --severity, --fail-on, --diff/--git-ref, and --baseline all affect what is reported, so they must match between environments.

For reproducible builds: pin your CodeCharter version in CI (see Versioning) and commit the .codecharter directory (config.yml and codecharter.lock.json). The lockfile pins each profile by content hash, and analyze stops with exit code 4 if a rule bundle no longer matches the hash recorded in the lockfile.

Consequences for Your Workflow

If a locally green build turns red in CI, one of the factors above has diverged. Typical causes:

  • Local and CI CodeCharter versions have diverged.
  • .codecharter/config.yml or codecharter.lock.json was not committed. (The .codecharter/cache/ directory is a local cache and does not belong in version control.)
  • codecharter.lock.json was updated in one environment but not the other, for example after codecharter update. Run codecharter verify to check the local rule cache against the lockfile; it exits with code 1 on drift.
  • The CI pipeline passes different analysis options than your local run.

See Local Findings Differ from CI for the debugging steps.