Violations

Violations

Violations are policy failures: an invariant compared a metric value to a threshold and the condition did not hold. Each violation records which metric, what was expected, what was actual, and the operator used.

What a Violation Contains

A policy violation (not to be confused with metric “findings” or layer “violations” in metrics) is:

• metric — The metric key that failed (e.g. scc.max_cycle_size).
• expected — The threshold value from the invariant (value in config).
• actual — The value produced by the metric (or missing → reported as NaN).
• op — The comparison operator (==, <=, >=, etc.).

Optional message from the invariant can be shown in CLI/reports for context.

When Violations Occur

1. Metric key missing — The invariant references a metric key that no selected metric produced (e.g. wrong key name or metric not in preset). Treated as failure; actual is reported as NaN.
2. Comparison failed — The metric produced a value but it did not satisfy the invariant (e.g. scc.max_cycle_size is 5 but invariant requires == 0).

Fail-Fast

• Default — All invariants are evaluated; all violations are collected and reported.
• Fail-fast — With --fail-fast or run_options.fail_fast: true, evaluation stops after the first violation. Used in CI for faster feedback: first failing gate fails the run immediately.

Violations vs Metric Findings

	Policy violations	Metric findings (e.g. layer “violations”)
Type	Invariant failed (expected vs actual)	Evidence from a metric (file, line, recommendation)
Produced by	Policy evaluator	Metric plugins (e.g. layer_violations, effect_violations, smells)
Content	Metric key, expected, actual, op	Finding type, severity, evidence list, recommendation

So: “policy violation” = invariant failed. “Layer violations” or “effect violations” are metric outputs (often with evidence) that you can then enforce with invariants (e.g. layer_violations.violations_count == 0).

Output

• Console — Violations printed to stderr; exit code non-zero if any.
• JSON — Violations in the report object for tooling.
• CI — Use --fail-fast to exit on first violation and fail the pipeline.

Learn More

• Policies — Defining invariants
• Policy Examples — Example invariants and messages
• Evidence — Metric findings with file/line/snippet