ripwire-layers

# Layers with ripwire > Nearest neighbours: > • You want the file→file dependency graph itself (not a health read) → `--deps` is step 2 below, or > go straight to it if you already know you want godfiles/cycles. > • Reviewing YOUR OWN diff for coupling risk, not a repo-wide sweep → **ripwire-change-check**. > • Unfamiliar subsystem, general risk sweep (not architecture-specific) → **ripwire-fresh-eyes**. Trigger: you want a factual picture of architectural health before a large refactor, or you're reviewing whether the codebase is trending toward or away from clean layering. `<dir>` = repo root. Every metric below has a NUMBER → THRESHOLD → ACTION — don't stop at reporting it. 1. **Layering rules** (if a rules file exists) — `ripwire <dir> --arch=rules.txt` Output: `<arch>` with violations listed by layer pair and file. Exit 2 = NEW violations found (CI gate). If no rules file exists yet, this step is the prompt to write one (grammar: `layer NAME = substr…`, `deny FROM -> TO`, `allow FROM -> TO`; `#` comments). **Action**: every violation is a concrete edge to either fix (remove the dependency) or explicitly `allow` (document why it's intentional) — don't leave it silently baselined forever. **Adopting rules on a codebase with existing debt** — the baseline workflow: - `ripwire <dir> --arch=rules.txt --baseline` — accept every CURRENT violation as known debt: writes a `.ripwire_arch_baseline` sidecar in the CWD (commit it), exits 0. - From then on, plain `--arch=rules.txt` suppresses baselined violations and exits 2 only on NEW ones — the gate stops the bleeding without demanding an up-front cleanup. - `--arch=rules.txt --baseline-update` — deliberately accept new debt by merging current violations into the sidecar (exit 0). Use sparingly, in its own reviewed commit. **`--arch=rules.txt` also emits `<metrics propagation_cost="X.XXX">`** — the DSM (design-structure-matrix) transitive-closure density: the fraction of the file-dep graph reachable from an average file (MacCormack; a validated coupling *form*, computed here as a directory-level estimate from name-based deps). **Direction: lower is better** — 0 means files are mostly isolated from each other's transitive reach, 1 means touching any file risks rippling through the whole tree. **Action at a high reading** (no fixed universal threshold — compare against this same repo's own history/other modules, or treat >0.3 as worth a look): a high propagation cost is a change-amplification TAX — every edit here is more likely to have knock-on effects. Don't just report the number; find which directories are driving it (the `<m path=... ca= ce=>` per-module rows) and formalize a boundary between them — a `layer`/`deny` rule in `rules.txt` that would have caught the coupling. 2. **Dependency health** — `ripwire <dir> --deps --legend=compact` Output: `<deps>` with `<health>` metrics: - `acd` (average component dependency) — lower is better - `nccd` (normalized CCD) — < 0.25 is healthy - `shape` — "horizontal" (layered, good) vs "vertical" (coupled, risk) Then `<godfiles>` ranked by `afferent` (dependents) — each godfile is an implicit layer boundary that hasn't been formalized. **`afferent`/cycles are validated defect predictors; `nccd` (Lakos) and the `--arch` Martin Ca/Ce/I/A/D `I`/`A`/`D`/`zone=` block are design heuristics — mechanistically plausible, widely implemented, but no independent outcome-based study has validated them. Trust the god-file/cycle read hardest; treat nccd/D as descriptive, not proof.** **Action**: a file in the top-3 by `afferent` is doing double duty as a de-facto layer boundary with no rule enforcing it — that's the concrete next step, not just a note: add it as a named `layer` in `rules.txt` and write the `deny` rules that keep new dependents out of its internals. A cycle in `--report` is worse than a high-afferent file — break it before formalizing anything downstream of it. 3. **Module clustering** — `ripwire <dir> --communities --legend=compact` Output: `<communities modules="N">` clusters with dominant directory and lead symbols. `<bridge edges="N">` shows where clusters are tightly coupled across module boundaries. High bridge counts between non-adjacent modules are the layering violations `--arch` catches. **Action**: a high bridge count between two clusters that AREN'T adjacent in your intended layering is the specific violation to gate — turn it into a `deny FROM -> TO` rule rather than leaving it as an observation; a high bridge count between clusters that ARE meant to talk to each other is fine and doesn't need a rule. 4. **Mermaid diagram** (optional, for visual review) — `ripwire <dir> --mermaid` Output: a `flowchart LR` Mermaid snippet with module nodes and inter-module call counts. Paste at mermaid.live to render. Edges labeled with high counts are the hot coupling seams — same action as step 3: a heavy edge crossing an intended boundary becomes a `deny` rule. ## Output Health summary: `shape=`, `nccd=`, `propagation_cost=`, cycle count (from `--report`), top 3 god-files, and any `--arch` violations. Classify overall health: healthy / at-risk / needs restructuring — and for anything "at-risk" or worse, name the specific boundary to formalize (which layer, which `deny` rule) rather than stopping at the classification.