Skip to content

Commit 081d869

Browse files
thymikeeclaude
andcommitted
docs(adr): narrow ADR 0032 to one replaceable import model
Adopt the maintainer's decision statement. Graph-based checks share one normalized import model whose implementation stays replaceable; list its actual consumers and the facts they need instead of tying it to the AST rules. Separate the semantic blockers (missed dynamic imports, orphan files) from migration costs (formatting, config comments, a path check for filesystem-placement rules), retarget the revisit triggers, and link the parser-gap follow-up #3293. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 0993bb0 commit 081d869

2 files changed

Lines changed: 46 additions & 23 deletions

File tree

‎docs/adr/0032-layering-graph-engine.md‎

Lines changed: 45 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# ADR 0032: Layering Graph Engine — Keep the Custom Edge Model
1+
# ADR 0032: Layering Graph Engine — Retain the Current Engine
22

33
## Status
44

@@ -8,12 +8,19 @@ whose production tree is `7dda0c2bf`'s; the harness lives only at that commit
88

99
## Rules at a glance
1010

11-
- R2, R4, R5, R6, R77, R78, R14 and R71 stay on the `resolveImportEdges` edge model. Neither
12-
dependency-cruiser 18.5 nor fallow 3.32 replaces them.
13-
- Every layering rule reads one edge model. Do not enforce a subset from a second import graph: both
14-
engines disagree with it (tables below), and about 20 AST and ownership rules keep it alive.
15-
- Fix the custom gap at the shared parser: `parseImports` misses TypeScript `import('x').T` type
16-
positions (9 file pairs). The fix may move the R9 type-cycle ratchet.
11+
- R2, R4, R5, R6, R77, R78, R14 and R71 stay on the current engine. Neither dependency-cruiser 18.5
12+
nor fallow 3.32 replaces them.
13+
- Graph-based checks share one normalized import model, today built by `parseImports` and
14+
`resolveImportEdges`. Do not enforce a subset of them from a second, disagreeing import graph.
15+
- The model's implementation remains replaceable. Besides these eight rules, it must supply
16+
resolved edges with value, type-only and dynamic kinds to R9/R10, R19, R73–R76 and
17+
`scripts/depgraph/`; named symbols and the binding residue of dynamic imports to R76; and raw
18+
specifier sites to R11 and R13. Eleven other registry entries read source ASTs or text only, and
19+
one reads paths only.
20+
- Fix the demonstrated parser gap in #3293: `parseImports` misses TypeScript `import('x').T` type
21+
positions (9 file pairs). It already parses an OXC AST for dynamic imports but scans static
22+
imports with regexes; read both from that AST, `TSImportType` included, keeping symbol and
23+
edge-kind semantics, rather than adding a second extractor.
1724
- Do not upgrade fallow to 3.x for `boundaries`; revisit on a [trigger](#revisit-triggers).
1825

1926
## Measured
@@ -118,25 +125,41 @@ ratchet admits.
118125

119126
## Decision
120127

121-
Keep custom. Each engine measured worse than the custom rules on these rules, and neither removes
122-
the custom graph:
128+
Retain the current engine because the evaluated replacements do not provide sufficient semantic
129+
parity and net simplification. Graph-based checks share one normalized import model; its
130+
implementation remains replaceable. Continue replacing generic algorithms and compiler-enforceable
131+
rules with maintained tools. Fix the demonstrated parser gap.
123132

124-
- **dependency-cruiser** matches custom on R2, R4, R5 and R71. It mislabels 46 pairs, lets a lazy
125-
`import()` hide behind a type position (the R77 miss), cannot see non-TS paths, needs a wrapper to
126-
fail on stale entries, and needs `typescript@<7` or `@swc/core` beside TypeScript 7 (+1.6 s).
127-
Adopting it for four rules would delete about 430 lines and put two disagreeing import graphs
128-
behind one gate.
129-
- **fallow** is already a dependency, adds no measurable time, and has the best stale gate. With no
130-
dynamic kind, R5's and R77's lazy-seam exemption becomes violations or misses. Its boundary
131-
findings carry no rule id or hint, its rule packs skip files no entry point reaches, and 3.x
132-
rejects the 73 `comment` fields in `.fallowrc.json`.
133+
The semantic blockers are the correctness gaps in the parity table:
134+
135+
- **dependency-cruiser** deduplicates a file's dependencies on a key that omits the dynamic and
136+
`import()`-type kinds. That mislabels 46 pairs and lets a lazy `import()` hide behind an
137+
`import()` type of the same target, the R77 miss.
138+
- **fallow** has no dynamic-import kind, so it flags the lazy seams R5 admits and misses R77's
139+
`import()`. Its rule packs skip files no entry point reaches, so it also misses an orphan runner
140+
module.
141+
142+
Simplification is limited. dependency-cruiser matches custom on R2, R4, R5 and R71, where migration
143+
would delete about 430 lines. The shared model stays for its other consumers, so the gate would read
144+
two import graphs that disagree.
145+
146+
The rest are migration costs, which would not decide the question on their own:
147+
148+
- dependency-cruiser needs `typescript@<7` or `@swc/core` beside TypeScript 7 (+1.6 s), and a
149+
wrapper that fails on `summary.baselineStale`. Its diagnostics carry no line.
150+
- fallow 3.x rejects the 73 `comment` fields in `.fallowrc.json`, and its boundary findings carry no
151+
rule id or hint. It adds no measurable time and has the best stale gate.
152+
- R14 and R71 are filesystem-placement policies. A non-TS path under `src/utils` needs a path check
153+
with either engine; that is not a failure of an import engine.
133154

134155
## Revisit triggers
135156

136-
- dependency-cruiser keys deduplication on the dependency type, and it can parse with TypeScript 7
137-
or the repository already ships swc.
138-
- fallow boundaries gain a dynamic-import kind and per-rule ids and messages.
139-
- The AST and ownership rules stop consuming `resolveImportEdges`, so one engine can own the graph.
157+
- dependency-cruiser keys deduplication on the dependency type.
158+
- fallow boundaries gain a dynamic-import kind, and its rule packs cover files no entry point
159+
reaches.
160+
- An engine can supply the shared import model above to the existing consumers with less total
161+
machinery than `parseImports` and `resolveImportEdges`. The source-only AST checks do not have to
162+
change first.
140163

141164
## Deletion
142165

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
| [0029 Daemon Policy](0029-daemon-policy.md) | `AGENT_DEVICE_DAEMON_POLICY`, confining a daemon's commands, devices, or device shutdown, and where operator rules are enforced for batch/replay steps |
3434
| [0030 Process Lock Exclusion](0030-process-lock-exclusion.md) | process-lock publication/reclaim/release, retained mutation guards, and the single-protocol upgrade boundary |
3535
| [0031 macOS Native App Backend](0031-macos-native-app-backend.md) | `AGENT_DEVICE_MACOS_APP_BACKEND`, driving macOS app sessions without XCTest Automation Mode, why pointer actions are accessibility actions only, and the ghost cursor |
36-
| [0032 Layering Graph Engine](0032-layering-graph-engine.md) | evaluating replacement of `scripts/layering/` graph rules with dependency-cruiser or fallow `boundaries`, why every layering rule reads one edge model, the measured edge-set and parity gaps, and the revisit triggers |
36+
| [0032 Layering Graph Engine](0032-layering-graph-engine.md) | evaluating replacement of `scripts/layering/` graph rules with dependency-cruiser or fallow `boundaries`, why graph-based layering checks share one replaceable import model, the measured edge-set and parity gaps, and the revisit triggers |
3737

3838
ADRs record *why*; the registries and gates they describe are the living source of truth — when
3939
prose and a registry disagree, the registry wins and the ADR needs a follow-up.

0 commit comments

Comments
 (0)