Layer Structure (Hierarchy)

Layer Structure (Hierarchy)

Metric ID

hierarchy

Overview

hierarchy measures how cleanly dependencies follow an inferred layer order.

It computes hierarchy quality on the SCC-condensed import graph, then scores:

• how much dependency weight flows upward
• how much forward flow skips expected intermediate layers
• how tree-like and orderable the structure is

Use this metric to detect layer erosion even when explicit layer rules are not configured. For strict allow/deny architecture rules, use Layer Violations.

Primary Keys (Current Contract)

These are the most useful CI/policy keys:

Key	What it means	Target
hierarchy.module.agony.weighted_depth_normalized	Weighted hierarchy penalty normalized by total edge weight and depth	Lower is better (0 ideal)
hierarchy.module.edge.upward_weight_ratio	Fraction of total dependency weight carried by upward/lateral edges	Lower is better (0 ideal)
hierarchy.module.edge.skip_layer_ratio	Fraction of edges that jump over intermediate layers	Lower is better
hierarchy.module.depth	Number of inferred module levels	Context-dependent
hierarchy.module.shape.orderability	Fraction of modules outside non-trivial SCCs	Higher is better
hierarchy.module.shape.feedforwardness_proxy	Forward-progress proxy from weighted edge deltas	Higher is better
hierarchy.module.shape.treeness_proxy	Tree-likeness proxy for branching vs merging	Higher is better

Additional Keys

Commonly used supporting keys:

• hierarchy.module.edge.upward_count
• hierarchy.module.edge.upward_ratio
• hierarchy.module.edge_count
• hierarchy.module.node_count
• hierarchy.module.layer_pair_breakdown (JSON data)
• hierarchy.module.upward_edges (JSON data)
• hierarchy.module.top_violators (top-k data)
• hierarchy.module.level_distribution (histogram data)

Optional function-scope keys (when available):

• hierarchy.function.depth
• hierarchy.function.edge.upward_ratio

Optional baseline delta keys (when configured):

• hierarchy.module.trend.agony_depth_normalized_delta
• hierarchy.module.trend.upward_ratio_delta
• hierarchy.module.trend.upward_weight_ratio_delta

Interpretation Bands

For top-level gating, start with upward_weight_ratio and weighted_depth_normalized:

Band	Suggested interpretation
< 0.08	Low hierarchy pressure
0.08 - 0.15	Moderate erosion
0.15 - 0.25	High erosion
>= 0.25	Critical hierarchy breakdown

skip_layer_ratio > 0.10 usually indicates missing middle-layer abstractions.

Policy Examples

Strict (new codebases)

metrics:
  - id: hierarchy

policy:
  invariants:
    - metric: hierarchy.module.edge.upward_weight_ratio
      op: "<="
      value: 0.05
      message: "Keep weighted upward dependencies near zero"
    - metric: hierarchy.module.agony.weighted_depth_normalized
      op: "<="
      value: 0.08
      message: "Avoid hierarchy erosion"
    - metric: hierarchy.module.edge.skip_layer_ratio
      op: "<="
      value: 0.10
      message: "Avoid skipping intermediate layers"

Pragmatic (legacy systems)

metrics:
  - id: hierarchy

policy:
  invariants:
    - metric: hierarchy.module.edge.upward_weight_ratio
      op: "<="
      value: 0.15
    - metric: hierarchy.module.agony.weighted_depth_normalized
      op: "<="
      value: 0.15
    - metric: hierarchy.module.edge.skip_layer_ratio
      op: "<="
      value: 0.20

Metric Config

metrics:
  - id: hierarchy
    enabled: true
    config:
      include_per_scc_breakdown: true
      top_violators_count: 10
      min_agony_threshold: 0.0
      enable_function_scope: true
      max_forward_jump_without_warning: 1
      findings_top_k: 20
      findings_min_weighted_penalty: 0.5
      baseline:
        module_agony_depth_normalized: 0.12
        module_upward_ratio: 0.08
        module_upward_weight_ratio: 0.10

CLI Usage

# Run only hierarchy
arxo analyze --metric hierarchy --format json

# Explain metric contract in CLI
arxo metrics explain hierarchy

Working with Results

Prioritize refactors in this order:

1. hierarchy.module.upward_edges entries with highest weighted penalty
2. hierarchy.module.top_violators modules
3. high skip_layer_ratio areas that need intermediate abstractions

Hierarchy vs Layer Violations

• hierarchy: inferred structure quality (heuristic, continuous score)
• layer_violations: explicit rule checks from architecture.layers (deterministic pass/fail)

Use both together:

• layer_violations enforces declared contracts
• hierarchy catches structural drift beyond explicit rules

Related Metrics

• Circular Dependencies - cycles and cycle-cut candidates
• Change Impact - transitive ripple potential
• Module Boundaries - community separation quality
• Layer Violations - explicit layer dependency/effect rule checks
• Layer Enforcement Guide - explicit layer rules