Policies

Policies

Policies define conditions that must hold for an analysis run to be considered passing. In Arxo, a policy is a set of invariants: each invariant compares a metric value to a threshold using an operator.

Policy Structure

policy:
  invariants:
    - metric: scc.max_cycle_size
      op: "=="
      value: 0
      message: "No circular dependencies"
    - metric: propagation_cost.system.ratio
      op: "<="
      value: 0.15

• metric — The metric key (e.g. scc.max_cycle_size, centrality.module.hub_like_count). Must match a key produced by the metrics you run.
• op — Comparison: ==, !=, <, <=, >, >=.
• value — The threshold (number).
• message (optional) — Human-readable description; useful in CI output and violations.

How Evaluation Works

1. After metrics run, all metric values are collected into a single map (metric key → number).
2. For each invariant, the engine looks up the metric key in that map.
3. If the key is missing, the invariant is treated as failed (e.g. metric not run or key renamed).
4. If present, actual value is compared to invariant.value using op. If the comparison fails, a policy violation is recorded.
5. With fail-fast (e.g. --fail-fast or run_options.fail_fast), evaluation stops after the first violation for faster CI.

Operators

Operator	Meaning	Example
==	Equal	scc.max_cycle_size == 0 (no cycles)
!=	Not equal
<	Less than
<=	Less than or equal	propagation_cost.system.ratio <= 0.15
>	Greater than
>=	Greater than or equal	centrality.module.hub_like_count >= 0 (often used as “must be 0”)

Policy vs Metric Findings

• Policy — Evaluates numeric metric values against thresholds. Produces violations (metric, expected, actual, op) when an invariant fails.
• Metric findings — Optional evidence produced by metrics (file, line, snippet, recommendation). These are findings attached to MetricResult, not policy violations.

Use both: invariants for pass/fail gates, findings for actionable evidence in reports.

Learn More

• Policy Examples — Real-world policy patterns
• Violations — What happens when invariants fail
• Configuration — Where to put policy in config