Debug a diagram
First, render one fixture
Section titled “First, render one fixture”pnpm harness run 'architecture/easy.json'Open its PNG and metrics JSON under out/. The PNG tells you whether the problem
is real; the metric names the enforced invariant.
Choose the owning stage
Section titled “Choose the owning stage”| Symptom | Begin here | Then inspect |
|---|---|---|
| Input accepted when invalid | program/<family>.ts |
shared validators in program/common.ts |
| Fact missing or misclassified | families/<family>.ts |
its normalize() result |
| Node overlap or wrong dimensions | measure/ |
selected placement strategy |
| Bad overall arrangement | place/place-graph.ts |
selected strategy module |
| Merged or ugly connectors | route/route-placement.ts |
router candidates, scoring, refinement |
| Label collision | label/place-edge-labels.ts |
candidate scan and reserved corridors |
| Wrong caps, shape, icon, colour | materialize/materialize-graph.ts |
named notation/policy module |
| Clipped title or legend | fit/frame-document.ts |
content extent calculation |
| Correct NGD, wrong pixels | harness render-svg.ts |
element serializer |
- Reproduce with the narrowest fixture or focused unit test. 2. Inspect the representation immediately before and
after the suspected stage. 3. Fix the owner rather than compensating downstream. 4. Run focused tests and the affected
harness family. 5. Inspect rendered PNGs before updating any golden expectation. 6. Finish with
pnpm verify.