Module Boundaries

Module Boundaries (Modularity)

Overview

modularity detects communities in the dependency graph and measures how well module boundaries are separated.

Outputs are emitted under modularity.*.

Quick Start

arxo analyze --metric modularity

What It Measures

Metric	What it tells you	Direction
modularity.module.best_q	Best partition quality found across configured gamma values	Higher is better
modularity.module.singleton_community_ratio	How fragmented the partition is (many singleton communities)	Lower is better
modularity.module.boundary_edge_ratio	Share of edges crossing communities	Lower is better
modularity.module.bridge_node_ratio	Share of modules acting as cross-community bridges	Lower is usually better

Interpretation Bands

Metric	Healthy	Watch	High risk
modularity.module.best_q	>= 0.30	0.20 - 0.30	< 0.20
modularity.module.singleton_community_ratio	<= 0.30	0.30 - 0.40	> 0.40
modularity.module.boundary_edge_ratio	<= 0.55	0.55 - 0.70	> 0.70

Use trend tracking with a baseline for large legacy codebases: improving direction matters as much as absolute thresholds.

Default Behavior

• Algorithm: leiden (louvain optional)
• Directed objective: enabled
• Weighted edges: enabled
• Deterministic seed: 42
• Gamma sweep: [0.5, 1.0, 1.5, 2.0]

Configuration

Use metric config under metrics[].config.modularity:

metrics:
  - id: modularity
    enabled: true
    config:
      modularity:
        algorithm: leiden
        directed: true
        weighted: true
        gamma_values: [0.5, 1.0, 1.5, 2.0]
        seed: 42
        max_levels: 10
        max_iterations: 100
        stability_runs: 0
        emit_findings: true
        findings_top_k: 10
        include_call_graph: true

Validation behavior:

• gamma_values: keeps finite positive values, sorted and de-duplicated.
• max_levels: clamped to 1..50.
• max_iterations: clamped to 1..1000.
• stability_runs: clamped to 0..50.
• findings_top_k: clamped to 1..100.

Output Contract

Always-emitted numeric keys

• modularity.module.best_q
• modularity.module.best_gamma
• modularity.module.community_count
• modularity.module.avg_community_size
• modularity.module.max_community_size
• modularity.module.min_community_size
• modularity.module.singleton_community_ratio
• modularity.module.boundary_edge_ratio
• modularity.module.partition_gini
• modularity.module.partition_entropy
• modularity.module.bridge_node_ratio
• modularity.phase.compute_ms
• modularity.phase.ui_ms

Always-emitted structured keys

• modularity.module.gamma_sweep_table
• modularity.module.communities_table
• modularity.module.nodes_table

Conditionally-emitted keys

• modularity.module.boundary_edges_topk when boundary edges exist
• modularity.module.bridge_nodes_topk when bridge nodes exist
• modularity.function.* when include_call_graph: true and call graph data is available
• modularity.cross.module_function_nmi when module/function overlap exists

Optional stability keys

When stability_runs > 0:

• modularity.module.stability.vi_mean
• modularity.module.stability.vi_std
• modularity.module.stability.consensus_score

Findings

The metric emits deterministic findings sorted by rule_id, then path, then line:

• arxo/modularity/low-q (best_q < 0.20)
• arxo/modularity/high-fragmentation (singleton_community_ratio > 0.30)
• arxo/modularity/bridge-node-hotspot (participation_coeff >= 0.62 and degree >= 5)
• arxo/modularity/high-boundary-coupling (boundary score at or above p95)

Policy Examples

Strict Gate

policy:
  invariants:
    - metric: modularity.module.best_q
      op: ">="
      value: 0.30
    - metric: modularity.module.boundary_edge_ratio
      op: "<="
      value: 0.55
    - metric: modularity.module.singleton_community_ratio
      op: "<="
      value: 0.30

Pragmatic Legacy Gate

policy:
  invariants:
    - metric: modularity.module.best_q
      op: ">="
      value: 0.20
    - metric: modularity.module.boundary_edge_ratio
      op: "<="
      value: 0.70

Related Metrics

• Circular Dependencies — cycles blur community boundaries
• Layer Structure — layering quality and modular boundaries reinforce each other
• Change Impact — boundary leakage increases ripple effects
• Critical Modules — hubs often act as bridge nodes across communities