Findings and Severities

A Finding is the smallest unit of output from CodeCharter. It represents a concrete location in code where a specific rule matched.

Anatomy of a Finding

Every Finding has:

Field	Content
Rule	Slug of the rule, e.g. DateTime-Direct-Usage
Severity	info, warn, or error
Category	Freely chosen; groups related rules
File	Absolute or relative path to the file
Line	Line number
Column	Optional, column number
Message	What was specifically found here
Recommendation	What to do about it (from @recommendation in the rule)

In JSON output:

{
  "rule": "DateTime-Direct-Usage",
  "severity": "warn",
  "category": "Testability",
  "file": "src/Domain/PricingEngine.cs",
  "line": 42,
  "column": 18,
  "message": "Direct call to DateTime.UtcNow",
  "recommendation": "Inject TimeProvider via constructor and call GetUtcNow()"
}

Severities

CodeCharter has three severity levels.

info

A hint. It does not block the build. Good for rules that catch nice-to-haves: "this spot would be more readable with the following refactoring idea". Be careful not to accumulate too many of these in day-to-day work, or they will be ignored.

warn

A warning. By default it does not block the build, but it is visible in the output and in the editor. Good for conventions you want to enforce but not block hard, such as async methods without a CancellationToken. Use --fail-on warn to make it a build blocker.

error

An error. By default it blocks the build when you set --fail-on error (the recommended setting for CI). Reserved for violations that truly must not reach the main branch: broken architecture, security vulnerabilities, explicitly forbidden APIs.

Which Severity to Use

Rule of thumb: as strict as necessary, as friendly as possible.

• error only when the violation would cause real harm (security, stability, contract breach).
• warn for conventions the team wants to enforce collectively, with the understanding that justified exceptions exist.
• info for style recommendations that are "better, but acceptable as-is".

A rule that uses only error because "if we're writing a rule it should have teeth" is an anti-pattern. Within days, devs will reach for // codecharter:disable instead of fixing the issue.

Overriding Severities per Location

In .codecharter/severity.cfg:

# Not treated as a build blocker in this repo
DateTime-Direct-Usage = warn

# Stricter than the default in this repo
Cognitive-Complexity = error

This lets you raise or lower built-in rules to match your team's standards on a per-repo basis.

Aggregation

In the build output, findings are sorted by severity, then file, then line. At the end of the run there is a summary:

Done in 28.4s. 17 findings (3 errors, 14 warnings, 0 infos)

For exit code behavior and CI integration see Exit Codes and Output Formats.