Skip to content
Arxo Arxo

Layer Violations

Layer Violations

Section titled “Layer Violations”

Metric ID

Section titled “Metric ID”

layer_violations

Overview

Section titled “Overview”

layer_violations enforces explicit architecture rules from architecture.layers.

It checks two things:

  • Disallowed dependencies between layers (can_depend_on)
  • Disallowed effects used from a layer (allowed_effects)

Unlike Hierarchy, this metric is rule-based and deterministic. It does not infer layers from graph shape.

Data Requirements

Section titled “Data Requirements”
  • Call graph
  • Effect index
  • architecture.layers configuration

If architecture.layers is missing, this metric fails with a config error.

Key Contract (Current)

Section titled “Key Contract (Current)”
KeyMeaning
layer_violations.violations_countTotal violations (dependency_violations + effect_violations)
layer_violations.dependency_violationsCount of disallowed cross-layer dependencies
layer_violations.effect_violationsCount of disallowed effects by layer policy
layer_violations.cross_depthAverage layer-distance per cross-layer edge
layer_violations.upward_calls_ratioShare of cross-layer edges that point upward in layer order
layer_violations.cross_layer_jump_ratioShare of cross-layer edges that skip at least one layer

Findings Emitted

Section titled “Findings Emitted”

layer_violations emits deterministic findings with these rule_id values:

  • arxo/layer-dependency-violation
  • arxo/layer-effect-violation

Configuration

Section titled “Configuration”

Define layers under architecture.layers:

architecture:
  layers:
    - name: presentation
      paths: ["src/ui/**"]
      allowed_effects: []
      can_depend_on: ["business", "shared"]


    - name: business
      paths: ["src/services/**"]
      allowed_effects: []
      can_depend_on: ["data", "shared"]


    - name: data
      paths: ["src/data/**"]
      allowed_effects: ["io", "network", "storage"]
      can_depend_on: ["shared"]


    - name: shared
      paths: ["src/shared/**"]
      allowed_effects: []
      can_depend_on: []


metrics:
  - id: layer_violations
    enabled: true

Rules:

  • Use paths (array), not path
  • can_depend_on must contain layer names, not path globs
  • Layer order in config is used for upward/jump ratios

Policy Examples

Section titled “Policy Examples”

Strict

Section titled “Strict”
policy:
  invariants:
    - metric: layer_violations.violations_count
      op: "=="
      value: 0
      message: "No layer rule violations allowed"

Incremental (legacy codebase)

Section titled “Incremental (legacy codebase)”
policy:
  invariants:
    - metric: layer_violations.violations_count
      op: "<="
      value: 20
    - metric: layer_violations.upward_calls_ratio
      op: "<="
      value: 0.10

CLI Usage

Section titled “CLI Usage”
Terminal window
# Run only layer_violations
arxo analyze --metric layer_violations --format json


# Explain metric in CLI
arxo metrics explain layer_violations
Section titled “Related”