|
| 1 | +# P-023 — Architecture guard (`Own.Arch`) |
| 2 | + |
| 3 | +- **Status:** draft — design accepted in discussion; implementation not started. |
| 4 | +- **Depends on:** [P-013](P-013-distribution-surface.md) (CI Action / dotnet tool |
| 5 | + surface — the guard rides the same delivery rails) and |
| 6 | + [P-015](P-015-configuration-surface.md) (severity policy vocabulary). Phase 2 |
| 7 | + reuses the Roslyn extraction stack from |
| 8 | + [P-001](P-001-csharp-extractor.md). Reporting reuses the SARIF export design |
| 9 | + from [`docs/notes/sarif-export.md`](../notes/sarif-export.md). |
| 10 | + |
| 11 | +## Motivation |
| 12 | + |
| 13 | +Architecture drift is the gap between the intended dependency structure of a |
| 14 | +codebase and what the code actually does. In a living solution it accumulates |
| 15 | +one "temporary" reference at a time: a ViewModel reaches into a SQL repository, |
| 16 | +a Domain project quietly picks up a DevExpress package, and six months later the |
| 17 | +layer diagram is fiction. |
| 18 | + |
| 19 | +Every attempt to fix this with a "detect everything bad" platform dies the same |
| 20 | +way: |
| 21 | + |
| 22 | +```text |
| 23 | +turn on the rules |
| 24 | +get 800 violations on day one |
| 25 | +downgrade everything to warnings |
| 26 | +nobody reads warnings |
| 27 | +initiative dead in a month |
| 28 | +``` |
| 29 | + |
| 30 | +Own.Arch deliberately does **not** build a SOLID detector, a documentation-sync |
| 31 | +checker, or a runtime-telemetry differ. The value proposition is one sentence: |
| 32 | + |
| 33 | +> **Own.Arch fails a PR if and only if it introduces a *new* architectural |
| 34 | +> dependency violation. Existing debt is baselined, ratcheted, and reported — |
| 35 | +> never a build blocker.** |
| 36 | +
|
| 37 | +Three artefacts, one direction of truth: |
| 38 | + |
| 39 | +```text |
| 40 | +intent model: architecture.rules.yaml (hand-written, reviewed) |
| 41 | +actual model: dependency graph extracted from .sln/.csproj/assemblies |
| 42 | +drift: actual − allowed → verdicts, gated against a baseline |
| 43 | +``` |
| 44 | + |
| 45 | +Diagrams, reports, and tests are all *generated from* the intent model. There is |
| 46 | +no second place where the intended architecture lives — no hand-maintained C4 |
| 47 | +model competing with the rules for source-of-truth status. |
| 48 | + |
| 49 | +## Scope |
| 50 | + |
| 51 | +### MVP: project-level dependency guard |
| 52 | + |
| 53 | +The MVP reads the solution's project graph — no compilation, no Roslyn — and |
| 54 | +gates on it: |
| 55 | + |
| 56 | +| Code | Finding | Default severity | Confidence | |
| 57 | +|------|---------|------------------|------------| |
| 58 | +| `ARCH001` | `ProjectReference` from layer X to layer Y not in the allowed graph | error (if not baselined) | deterministic — it is an edge in a graph | |
| 59 | +| `ARCH002` | Forbidden `PackageReference` / `packages.config` entry in a layer (e.g. SQL provider in Domain) | error (if not baselined) | deterministic for direct references | |
| 60 | +| `ARCH003` | Project matches no layer pattern, or matches more than one | error, never baselinable | configuration defect — default deny | |
| 61 | +| `ARCH030` | Allowed edge that no project actually uses (reverse drift: the intent model is rotting) | info / report only | deterministic | |
| 62 | + |
| 63 | +`ARCH003` is the discipline rule: an unmapped project is a hole in the guard, |
| 64 | +so the mapping is forced to stay total and unambiguous. The cheapest bypass — |
| 65 | +name the project `Broker.Utils` and reference whatever you like — must not |
| 66 | +exist. |
| 67 | + |
| 68 | +`ARCH030` is what distinguishes a guard from yet another linter: the intent |
| 69 | +model decays too, and "declared but unused dependency" is the only automatic |
| 70 | +signal of that decay. |
| 71 | + |
| 72 | +### Phase 2: type-level facts |
| 73 | + |
| 74 | +After the project-level guard has survived contact with a real solution: |
| 75 | + |
| 76 | +| Code | Finding | Default severity | Confidence | |
| 77 | +|------|---------|------------------|------------| |
| 78 | +| `ARCH010` | Type in layer X depends on a type in layer Y outside the allowed graph (catches violations invisible at project granularity) | error (if not baselined) | deterministic on compiled IL / semantic model | |
| 79 | +| `ARCH011` | Forbidden API used in a layer (`System.Windows.MessageBox` in Domain, `SqlConnection` in Application, …) | error (if not baselined) | deterministic | |
| 80 | +| `ARCH012` | Namespace-level dependency cycle | warning at first, error once trusted | deterministic | |
| 81 | + |
| 82 | +Note: there is deliberately no *project*-level cycle rule — MSBuild already |
| 83 | +refuses to build circular `ProjectReference` graphs. Cycle detection only means |
| 84 | +something at namespace/type granularity, which is why it lives in phase 2. |
| 85 | + |
| 86 | +### Phase 3: heuristic signals (never build blockers at introduction) |
| 87 | + |
| 88 | +| Code | Finding | Default severity | Confidence | |
| 89 | +|------|---------|------------------|------------| |
| 90 | +| `ARCH020` | Type has too many distinct dependencies (fan-out / god-class signal) | warning | heuristic | |
| 91 | +| `ARCH021` | Type in layer X mixes APIs from layers Y and Z (SRP *symptom*, not SRP verdict) | warning | heuristic | |
| 92 | +| `ARCH022` | Interface with too many members (ISP symptom) | warning | heuristic | |
| 93 | +| `ARCH040` | Duplicated code blocks / dead public API | report only | noisy — see Non-goals | |
| 94 | + |
| 95 | +The tiering is the honest answer to "can you detect SOLID?": no. You can |
| 96 | +detect **dependency facts** (deterministic — tier 1), **structural symptoms** |
| 97 | +(heuristic — tier 2), and **quality smells** (noisy — tier 3). Selling tier 3 |
| 98 | +as tier 1 is how analyzers lose trust. Dead-code detection in particular, in a |
| 99 | +.NET codebase with reflection, DI containers, serialization, and XAML bindings, |
| 100 | +false-positives constantly; failing a build on it is out of the question. |
| 101 | + |
| 102 | +## Non-goals |
| 103 | + |
| 104 | +- **No C4 model as source of truth.** C4/PlantUML/Mermaid diagrams are a |
| 105 | + *rendering* of `architecture.rules.yaml`, generated in CI, never |
| 106 | + hand-edited, never diffed as images. A hand-maintained architecture model |
| 107 | + plus separate rules is two parrots arguing about who is the architect. |
| 108 | +- **No runtime telemetry diffing** (OpenTelemetry traces vs. declared |
| 109 | + architecture). Valuable someday; a separate infrastructure project; not here. |
| 110 | +- **No dead-code or clone-detection quality gates.** Report-only, forever, or |
| 111 | + until someone proves the false-positive rate on *our* corpus is near zero. |
| 112 | +- **No test-coverage or documentation-freshness "drift" checks.** Those are |
| 113 | + quality gates, not architecture; bundling them is how the scope eats the |
| 114 | + tool. |
| 115 | +- **No second rule DSL.** No generated ArchUnitNET/NetArchTest test code. One |
| 116 | + intent model (`rules.yaml`), one evaluator that reads it directly. If |
| 117 | + type-level extraction needs a library (Cecil, Roslyn), it is used as an |
| 118 | + *extractor*, not as a rule language. |
| 119 | +- **No hard dependency on commercial tooling** (NDepend et al.). Optional |
| 120 | + later evaluation at most. |
| 121 | +- **No "SOLID detector" claim.** The rules are SOLID-*inspired*; the README |
| 122 | + should say "dependency and layering guard", nothing grander. |
| 123 | + |
| 124 | +## Sketch |
| 125 | + |
| 126 | +The seam is the same deep-module interface as the rest of Own.NET: |
| 127 | + |
| 128 | +```text |
| 129 | +.sln/.csproj/packages.config --[extractor]--> arch-facts.json |
| 130 | + | |
| 131 | +architecture.rules.yaml ----------------------\ | |
| 132 | +architecture-baseline.json ---------------------+---+--[core]--> ARCH### verdicts |
| 133 | + --> SARIF + markdown report |
| 134 | + --> (later) Mermaid/C4 diagrams |
| 135 | +``` |
| 136 | + |
| 137 | +The extractor emits facts; the core owns verdicts — the "one checker" rule |
| 138 | +holds. MVP facts are plain XML reads of project files; phase 2 adds an IL or |
| 139 | +Roslyn pass emitting type-dependency facts in the same JSON envelope. |
| 140 | + |
| 141 | +### `architecture.rules.yaml` (intent model) |
| 142 | + |
| 143 | +```yaml |
| 144 | +layers: |
| 145 | + Presentation: |
| 146 | + matches: ["*.Presentation", "*.Wpf", "*.Client"] |
| 147 | + Application: |
| 148 | + matches: ["*.Application", "*.Services"] |
| 149 | + Domain: |
| 150 | + matches: ["*.Domain", "*.Core"] |
| 151 | + DomainAbstractions: |
| 152 | + matches: ["*.Domain.Abstractions"] |
| 153 | + Infrastructure: |
| 154 | + matches: ["*.Infrastructure", "*.DataAccess"] |
| 155 | + |
| 156 | +# Direct edges only. No transitive closure is implied: |
| 157 | +# Presentation -> Application -> Domain does NOT allow Presentation -> Domain. |
| 158 | +allowedDependencies: |
| 159 | + Presentation: [Application, DomainAbstractions] |
| 160 | + Application: [Domain, DomainAbstractions] |
| 161 | + Infrastructure: [Domain, DomainAbstractions] |
| 162 | + Domain: [DomainAbstractions] |
| 163 | + |
| 164 | +forbiddenPackages: |
| 165 | + Domain: [System.Data.SqlClient, Microsoft.Data.SqlClient, DevExpress*, Newtonsoft.Json] |
| 166 | + Application: [DevExpress*, PresentationFramework] |
| 167 | + |
| 168 | +# Phase 2: |
| 169 | +forbiddenApis: |
| 170 | + Domain: [System.Windows.*, System.Data.*] |
| 171 | + Application: [System.Windows.MessageBox] |
| 172 | +``` |
| 173 | +
|
| 174 | +Resolution rules, fixed up front: |
| 175 | +
|
| 176 | +- A project matching zero or ≥2 layer patterns is `ARCH003` — config error, |
| 177 | + cannot be baselined or suppressed. |
| 178 | +- Package checks cover **direct** references only in the MVP. |
| 179 | + `packages.config` is flat, so legacy solutions get full coverage for free; |
| 180 | + SDK-style transitive dependencies need `project.assets.json` parsing and are |
| 181 | + explicitly deferred (recorded limitation, not silent gap). |
| 182 | + |
| 183 | +### `architecture-baseline.json` (the ratchet) |
| 184 | + |
| 185 | +Existing violations are frozen at adoption time; the gate only fires on *new* |
| 186 | +ones. This is the load-bearing element — without it the guard is architectural |
| 187 | +theatre. |
| 188 | + |
| 189 | +```json |
| 190 | +{ |
| 191 | + "rulesHash": "sha256:…of architecture.rules.yaml…", |
| 192 | + "violations": [ |
| 193 | + { |
| 194 | + "rule": "ARCH001", |
| 195 | + "from": "Broker.Domain", |
| 196 | + "to": "Broker.Infrastructure", |
| 197 | + "fingerprint": "sha256:ab12…", |
| 198 | + "firstSeen": "2026-07-03", |
| 199 | + "reason": "legacy tax calculator; tracked as TECH-482" |
| 200 | + } |
| 201 | + ] |
| 202 | +} |
| 203 | +``` |
| 204 | + |
| 205 | +**Fingerprint policy (the make-or-break detail):** |
| 206 | + |
| 207 | +- `fingerprint = sha256(rule ‖ normalized-from-symbol ‖ normalized-to-symbol)`. |
| 208 | + **No file paths, no line numbers** — a positional fingerprint churns the |
| 209 | + baseline on every refactor; a looser one lets new violations impersonate old |
| 210 | + ones. |
| 211 | +- Consequence, accepted deliberately: renaming a symbol makes the old entry |
| 212 | + "fixed" and the new one "new" → FAIL. That is correct behaviour — it forces |
| 213 | + a conscious baseline update in the same PR — but only tolerable if updating |
| 214 | + is one command: |
| 215 | + |
| 216 | + ```text |
| 217 | + own-arch baseline accept --reason "rename only, no new edge" |
| 218 | + ``` |
| 219 | + |
| 220 | + A mandatory `--reason` is the whole suppression policy; entries without one |
| 221 | + are rejected. |
| 222 | +- The file is **canonically sorted, one violation per line**, so concurrent |
| 223 | + PRs merge without conflicts. |
| 224 | +- `rulesHash` pins the baseline to the rules version. Tightening a rule |
| 225 | + invalidates the baseline; the same PR that changes the rules regenerates it. |
| 226 | + A stale hash is a build error, not a silent re-interpretation. |
| 227 | + |
| 228 | +**CI decision table:** |
| 229 | + |
| 230 | +| Observation | Verdict | |
| 231 | +|---|---| |
| 232 | +| known violation still present | OK (counted, reported) | |
| 233 | +| known violation gone | GOOD — entry removed (or PR comment nudges removal) | |
| 234 | +| new violation | **FAIL** | |
| 235 | +| baseline entry count grew without `--reason` entries | **FAIL** (fallback invariant; normally subsumed by "new → FAIL") | |
| 236 | +| `rulesHash` mismatch | **FAIL** — regenerate baseline alongside the rules change | |
| 237 | + |
| 238 | +There is no separate "violation changed → REVIEW" state: with symbol-pair |
| 239 | +fingerprints, "changed" decomposes into "one gone + one new", and the policy |
| 240 | +above already covers both halves. |
| 241 | + |
| 242 | +### Reporter |
| 243 | + |
| 244 | +- **SARIF** as the primary machine output — GitHub code scanning and Azure |
| 245 | + DevOps render it as inline PR annotations for free |
| 246 | + (see [`sarif-export.md`](../notes/sarif-export.md); same format, same |
| 247 | + rails). |
| 248 | +- **Markdown summary** for the PR conversation: new violations first, then the |
| 249 | + ratchet status (`baseline: 47 known, −2 this PR`), then `ARCH030` reverse |
| 250 | + drift. |
| 251 | +- Violation messages name both endpoints and the rule, and suggest the |
| 252 | + layer-correct alternative: |
| 253 | + |
| 254 | + ```text |
| 255 | + ARCH001: Broker.Presentation.DeclarationViewModel → Broker.Infrastructure.SqlCustomerRepository |
| 256 | + Presentation may depend on: Application, Domain.Abstractions. |
| 257 | + Fix: call an Application service or a Domain abstraction instead. |
| 258 | + ``` |
| 259 | + |
| 260 | +- **Later:** generate Mermaid/PlantUML (optionally via C4 tooling as a pure |
| 261 | + renderer) from `rules.yaml`, and overlay the *actual* graph with drift edges |
| 262 | + highlighted. The intended diagram and the drift diagram come from the same |
| 263 | + two inputs the gate already has — no third model. |
| 264 | + |
| 265 | +## Implementation order |
| 266 | + |
| 267 | +Weeks are calendar-honest, not research-project-honest: |
| 268 | + |
| 269 | +1. **Week 1 — the ratchet works end to end.** `rules.yaml` schema + parser; |
| 270 | + `.sln`/`.csproj`/`packages.config` extractor; `ARCH001`–`ARCH003` |
| 271 | + evaluation; baseline generate/accept/check; CI wiring. |
| 272 | + **Exit criterion: on a real solution, the baseline is frozen and a |
| 273 | + deliberately broken PR goes red.** A green pipeline proves nothing; the red |
| 274 | + PR is the acceptance test. |
| 275 | +2. **Week 2 — feedback quality.** SARIF + markdown reporter; `--reason` |
| 276 | + suppression flow; `ARCH030` reverse drift; docs for "my PR went red, what |
| 277 | + now". |
| 278 | +3. **Week 3 — type-level facts.** IL/Roslyn dependency extraction feeding |
| 279 | + `ARCH010`–`ARCH012`; forbidden-API list; same baseline mechanics (the |
| 280 | + fingerprint scheme already accommodates type-granularity symbols). |
| 281 | +4. **Later, separately justified:** phase-3 heuristics as warnings; diagram |
| 282 | + generation; transitive package closure via `project.assets.json`; |
| 283 | + multi-solution/monorepo layout support. |
| 284 | + |
| 285 | +## Open questions |
| 286 | + |
| 287 | +1. **Where does the evaluator live?** The one-checker rule says the Python core |
| 288 | + owns verdicts (extractor emits `arch-facts.json`, core evaluates). But |
| 289 | + unlike ownership analysis, this checker is a graph-set difference — trivial |
| 290 | + in either language — and a self-contained dotnet tool is easier to adopt in |
| 291 | + C#-only shops. Leaning: follow the house seam (facts → Python core) for |
| 292 | + consistency and shared reporting, but keep the fact schema tool-agnostic so |
| 293 | + a standalone runner remains possible. |
| 294 | +2. **Phase-2 extraction: Mono.Cecil over compiled assemblies, or Roslyn over |
| 295 | + source?** Cecil sees what actually ships (including generated code) but |
| 296 | + needs a build first; Roslyn integrates with the P-001 stack and sees |
| 297 | + pre-build. Leaning: Cecil for dependency edges (cheap, whole-assembly), |
| 298 | + Roslyn only if forbidden-API checks need syntax-level precision. |
| 299 | +3. **Does `rules.yaml` fold into the P-015 configuration surface,** or stay a |
| 300 | + separate file? Leaning: separate file — it is a reviewed architectural |
| 301 | + artefact with its own change ceremony, not a per-developer knob. |
| 302 | +4. **Fingerprint stability at type granularity:** namespace-qualified type |
| 303 | + pairs churn more than project pairs under refactoring. Is `(rule, from-type, |
| 304 | + to-type)` right, or should type-level entries baseline at |
| 305 | + `(rule, from-namespace, to-namespace)` to reduce accept-noise? Needs a trial |
| 306 | + run on a real diff history. |
| 307 | +5. **Naming/positioning:** `Own.Arch` as a product family next to `Own.Async` / |
| 308 | + `Own.React`, or a subcommand of the existing CLI? Affects P-013 packaging |
| 309 | + only; the seam is unchanged either way. |
0 commit comments