Coupling Analysis

Coupling Analysis

Overview

coupling_analysis is a composite module-level risk metric. It combines structural and historical signals to highlight modules that are most likely to amplify changes across the system.

The model blends:

• Structural coupling (centrality + degree + churn)
• Logical coupling (co-change and mismatch patterns)
• Instability (Ce / (Ca + Ce))
• Ownership concentration (HHI + bus-factor component)

This metric is useful for triaging architecture debt and prioritizing refactors.

Version

• Current public contract: coupling_analysis v2.0.0
• This is a breaking redesign from earlier hotspot/quadrant output.

Key Outputs

Summary keys

• coupling_analysis.module_count
• coupling_analysis.risk_index
• coupling_analysis.critical_module_count
• coupling_analysis.high_module_count
• coupling_analysis.medium_module_count
• coupling_analysis.logical_mismatch_pair_count
• coupling_analysis.unstable_core_count
• coupling_analysis.ownership_core_risk_count
• coupling_analysis.avg_structural_score
• coupling_analysis.avg_logical_score
• coupling_analysis.avg_instability_score
• coupling_analysis.avg_ownership_score
• coupling_analysis.avg_composite_score

Ranked/table outputs

• coupling_analysis.top_composite_risk_modules
• coupling_analysis.modules_risk_table
• coupling_analysis.logical_mismatch_table

Findings

When enabled, the metric emits findings with these rule IDs:

• coupling_analysis.critical_hotspots
• coupling_analysis.logical_mismatch
• coupling_analysis.unstable_core
• coupling_analysis.ownership_core_risk

Configuration

metrics:
  - id: coupling_analysis
    enabled: true
    config:
      hotspot_percentile: 0.80
      core_percentile: 0.75
      logical_mismatch_min_cochange: 3
      instability_unstable_threshold: 0.70
      ownership_high_threshold: 0.70
      top_risk_limit: 10
      weights:
        structural: 0.40
        logical: 0.30
        instability: 0.20
        ownership: 0.10

Weights are normalized at runtime.

Requirements and Caveats

• Requires Git history for logical coupling and churn signals.
• Uses computed metrics (including centrality) as upstream inputs.
• If centrality betweenness is unavailable, structural scoring is less informative.

Policy Examples

policy:
  invariants:
    - metric: coupling_analysis.risk_index
      op: "<="
      value: 0.45
      message: "Keep overall coupling risk below 0.45"
    - metric: coupling_analysis.critical_module_count
      op: "=="
      value: 0
      message: "No critical coupling hotspots"

Migration Notes (Legacy -> v2)

Legacy keys such as coupling_analysis.avg_hotspot, coupling_analysis.max_hotspot, and coupling_analysis.quadrant_* were removed.

Prefer:

• coupling_analysis.risk_index
• coupling_analysis.top_composite_risk_modules
• coupling_analysis.modules_risk_table