|
| 1 | +# Change-coupling report |
| 2 | + |
| 3 | +```sh |
| 4 | +pnpm coupling # -> .tmp/coupling/report.json + a text summary |
| 5 | +pnpm coupling --since-days 30 --out /tmp/coupling.json |
| 6 | +pnpm coupling:test |
| 7 | +``` |
| 8 | + |
| 9 | +Logical coupling from git history alone: do the physical families (workspace packages and |
| 10 | +`src/` zones) match how the repository actually changes? There is no renderer; the JSON is the |
| 11 | +artifact and the text summary is the headline. |
| 12 | + |
| 13 | +## What it answers |
| 14 | + |
| 15 | +- **Affinity.** A commit touching `k >= 2` production files adds `1 / (k - 1)` to each unordered |
| 16 | + pair; `support` counts the commits containing the pair. Commits over 60 files are mass |
| 17 | + migrations and are skipped and listed, never folded in. Edges below support 3 are cut. |
| 18 | +- **Family modularity.** With `W` the kept weight, `in_f` the weight inside family `f`, `out_f` |
| 19 | + the weight leaving it, and `s_f = 2·in_f + out_f`: `intraShare = Σ in_f / W`, |
| 20 | + `expected = Σ (s_f / 2W)²`, `Q_f = in_f / W − (s_f / 2W)²`. `Σ Q_f = intraShare − expected`, |
| 21 | + asserted in `modularity.test.ts`. `expected` is what a size-matched random rewiring would keep |
| 22 | + inside families; the difference is what the families hold beyond their size. |
| 23 | +- **Family span.** Distinct families per commit: histogram, median over commits spanning at |
| 24 | + least two families, and the share spanning five or more. |
| 25 | +- Everything is computed twice, over all history and over the trailing window (`--since-days`, |
| 26 | + default 120), so drift is visible in one document. |
| 27 | + |
| 28 | +## What the numbers do not mean |
| 29 | + |
| 30 | +**This is not a removability or correctness claim.** Co-change says two files were edited in the |
| 31 | +same commits; it does not say either imports the other, that one could move, or that anything |
| 32 | +is wrong. A file with a high hub weight is a place to look, never a work list. In particular: |
| 33 | + |
| 34 | +- `Q_f ≈ 0` with a large `out/in` flow says a family's changes land together with other |
| 35 | + families' changes. Whether that is a toolbox (`host-kit`), a vocabulary (`contracts`), or a |
| 36 | + wrongly-drawn boundary (`cli-schema`) is a reading the report cannot make for you. |
| 37 | +- A high `Q_f` says a family's changes stay inside it. `daemon-server` scores highest partly |
| 38 | + because it is the largest family; the `expected` term corrects for size only in aggregate. |
| 39 | +- The mass-commit threshold is a declared cut, not a detector. A 59-file refactor still counts. |
| 40 | +- The trailing window is only as good as the commits in it; a 30-day window on a quiet month is |
| 41 | + a coin toss. |
| 42 | + |
| 43 | +## Reference values (2026-09-19, commit a556e114cd) |
| 44 | + |
| 45 | +| | all-time | last 120 days | |
| 46 | +| --- | --- | --- | |
| 47 | +| commits used for pairs / skipped (> 60 files) | 1,044 / 34 | 779 / 31 | |
| 48 | +| kept edges at support ≥ 3 | 6,314 | 5,297 | |
| 49 | +| cross-family share of kept edges | 64.3% | 62.5% | |
| 50 | +| intraShare vs expected | 36.5% vs 11.5% | 39.7% vs 11.6% | |
| 51 | +| modularity | 0.250 | 0.282 | |
| 52 | +| median span of multi-family commits | 4 | 4 | |
| 53 | +| multi-family commits spanning ≥ 5 families | 37.6% | 39.6% | |
| 54 | + |
| 55 | +Heaviest hubs by out-family weight: `src/cli-schema/command-schema.ts` (96.5, reaches 22 |
| 56 | +families), `src/client/client-types.ts` (89.2, 26), `src/cli-schema/cli-help.ts` (85.7, 26), |
| 57 | +`src/cli.ts` (72.2, 21). Heaviest family pairs: `commands <-> daemon-server` (60.6), |
| 58 | +`cli-schema <-> daemon-server` (57.0), `daemon-server <-> platform-apple` (52.0). |
| 59 | + |
| 60 | +A drift warning is printed, never a failure, when all-time modularity leaves 0.20–0.35, the |
| 61 | +cross-family share drops under 60%, or the ≥ 5-family share drops under 25%. |
| 62 | + |
| 63 | +## What is authoritative |
| 64 | + |
| 65 | +`scripts/layering/` is, for the file set and the family partition: families are |
| 66 | +`targetDagZone` from `scripts/layering/model.ts` and the file set is `listSourceFiles`, exactly as |
| 67 | +`pnpm check:layering` sees them. History comes from `scripts/repo-history/`, the same model the |
| 68 | +legibility report reads, so both reports describe one tree. Nothing here gates, ratchets, or |
| 69 | +allowlists; the `coupling:test` gate proves the formulas on the committed fixture mini-repo in |
| 70 | +`scripts/repo-history/__fixtures__/`, not the live numbers. |
| 71 | + |
| 72 | +## What the JSON carries |
| 73 | + |
| 74 | +- `generated` — commit, date, file and family counts. |
| 75 | +- `window.allTime` / `window.since` — commit counts (total, touching, used, skipped, threshold), |
| 76 | + the skipped commits, edge counts with the cross-family share, and the span histogram. |
| 77 | +- `assortativity` — `intraShare`, `expected`, `modularity` for both windows. |
| 78 | +- `perFamily[]` — `family, files, inWeight, outWeight, outInFlow, partners, Q` (all-time). |
| 79 | +- `hubs[]` — top files by kept weight with out-family weight and families reached. |
| 80 | +- `familyPairs[]` — cross-family weight per unordered family pair. |
| 81 | +- `edges[]` — every kept edge, `{ a, b, weight, support }`. |
0 commit comments