morpharch 2.2.3

Monorepo architecture drift visualizer with animated TUI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# Architectural Health Scoring

MorphArch translates dependency structure into a `0-100` health score.

## How the Score Works

MorphArch starts at `100` and subtracts debt when the graph shows structural
problems that make the repository harder to change.

The score combines six debt components and scales expectations based on
repository size, so larger systems are not penalized for every bit of normal
complexity.

All component weights, thresholds, and exemptions are
[configurable](../guides/configuration) via `morpharch.toml`. The percentages
below are the defaults.

---

## 1. Cycle Debt (default: 30%)

Cycles are one of the clearest signs that module boundaries are no longer
clean.

- **Detection**: uses strongly connected component analysis.
- **Impact**: accounts for up to 30% of total architectural debt by default.
- **Why it matters**: cycles make local changes harder to reason about.

---

## 2. Layering Debt (default: 25%)

Boundaries define the intended flow of your architecture. High-level modules
should depend on low-level modules, not the reverse.

- **Detection**: combines structural layering violations with explicit
  [boundary rules](../guides/configuration#boundary-rules) from
  `morpharch.toml`.
- **Impact**: accounts for up to 25% of total debt by default.
- **Why it matters**: boundary violations create ripple effects across the repo.

---

## 3. Hub / God Module Debt (default: 15%)

Hub modules are modules that have accumulated too much coordination pressure.

- **Detection**: penalizes modules with abnormally high incoming and outgoing
  dependency counts relative to the graph.
- **Entry-point exemption**: MorphArch ignores natural entry points such as
  `main`, `index`, `app`, `lib`, and `mod` by default.
- **Shared core exemption**: modules with a low
  `fan_out / (fan_in + 1)` ratio can be treated as legitimate shared cores.
- **Impact**: accounts for up to 15% of total debt by default.

---

## 4. Coupling Debt (default: 12%)

Large systems are naturally complex, but excessive connections lead to
fragility.

- **Detection**: measures weighted coupling intensity based on import counts
  between modules.
- **Impact**: accounts for up to 12% of total debt by default.
- **Scale grace**: larger monorepos are given more leniency for natural
  coupling than smaller ones.

---

## 5. Cognitive Debt (default: 10%)

Can a developer still reason about the graph without tracing too many links?

- **Detection**: evaluates graph density and distribution complexity.
- **Impact**: accounts for up to 10% of total debt by default.
- **Why it matters**: an architecture can compile and still be too dense to
  reason about safely.

---

## 6. Instability Debt (default: 8%)

Fragile modules are a risk. A module is fragile if it depends on many other
modules, but few things depend on it.

- **Detection**: uses instability-oriented dependency ratios and thresholding.
- **Exception**: leaf nodes, entry points, and items listed in
  `instability_exempt` are excluded from this penalty.
- **Impact**: accounts for up to 8% of total debt by default.

---

## Customizing the Scoring Engine

All defaults above can be overridden in `morpharch.toml`:

```toml
[scoring.weights]
cycle = 35
hub = 20
instability = 5

[scoring.thresholds]
hub_exemption_ratio = 0.25
brittle_instability_ratio = 0.85

[scoring.exemptions]
hub_exempt = ["deno_core"]
entry_point_stems = ["main", "index", "app", "lib", "mod"]
```

Weights are normalized internally so they always sum to 100%. See the
[Configuration Guide](../guides/configuration) for the full reference.

---

## How to Improve Your Score

1. **Break cycles**: use interfaces, traits, or extracted lower-level modules.
2. **Reduce boundary violations**: push dependencies back in the intended
   direction.
3. **Split oversized hubs**: refactor large coordinators into smaller modules.
4. **Review hotspots and blast radius**: MorphArch surfaces the modules creating
   the most risk and the widest downstream impact.
5. **Tune your config carefully**: prefer exemptions and explicit boundaries
   over simply ignoring problematic areas.