b381290f34
Pure-Dart P2c slice: interval-aware ports and corridors, label-aware lane spacing, measured label placement with fallback shelf, skipped diagnostics and routing bounds. 20 focused tests plus existing suite and web build pass.
117 lines
6.8 KiB
Markdown
117 lines
6.8 KiB
Markdown
# P2c — deterministic orthogonal edge and label routing
|
|
|
|
## What changed
|
|
|
|
New app-only, pure-Dart files. No existing file, server, web client, legacy
|
|
client, shell, `main.dart`, pubspec, domain, layout, other feature or platform
|
|
source was edited.
|
|
|
|
| File | Lines | Responsibility |
|
|
| --- | --- | --- |
|
|
| `lib/features/graph/routing/route_models.dart` | 261 | public route, port, label, diagnostic and bounds types |
|
|
| `lib/features/graph/routing/routing_inputs.dart` | 64 | measured label extents and caller clearances |
|
|
| `lib/features/graph/routing/route_geometry.dart` | 175 | axis track allocator and column-gap bands |
|
|
| `lib/features/graph/routing/corridor_plan.dart` | 105 | vertical corridor allocation per column gap |
|
|
| `lib/features/graph/routing/edge_route_planner.dart` | 265 | forward/back/same-rank/self-loop polyline planning |
|
|
| `lib/features/graph/routing/edge_label_placement.dart` | 175 | measured label boxes clear of nodes and other labels |
|
|
| `lib/features/graph/routing/graph_edge_routing.dart` | 135 | validation, skipped diagnostics, labels, total bounds |
|
|
| `test/features/graph/routing/routing_fixtures.dart` | 143 | chain/diamond/parallel/cycle/self-loop/disconnected fixtures |
|
|
| `test/features/graph/routing/routing_assertions.dart` | 215 | orthogonality, borders, node interiors, corridors, labels, bounds |
|
|
| `test/features/graph/routing/graph_edge_routing_test.dart` | 191 | chain, diamond, parallel, cycle, loop, disconnected, expanded text, unknown targets |
|
|
| `test/features/graph/routing/graph_routing_geometry_test.dart` | 161 | wide labels, tight gaps, 3-stage SCC, backward layout, loop + forwards |
|
|
| `test/features/graph/routing/graph_routing_validation_test.dart` | 222 | empty input, missing measurements, duplicate ids, invalid config, determinism/immutability |
|
|
|
|
No painting, widgets, styling, shell wiring or font/CSS/device constants were
|
|
added.
|
|
|
|
## Public API
|
|
|
|
```dart
|
|
GraphRouting routeGraphEdges({
|
|
required GraphLayout layout,
|
|
required List<GraphEdge> edges,
|
|
required Map<int, LabelExtent> labelExtents,
|
|
required RoutingConfig config,
|
|
});
|
|
```
|
|
|
|
`RoutingConfig` takes `nodeClearance`, `laneSpacing`, `corridorSpacing`,
|
|
`portSpacing`, `labelGap` and optional `boundsPadding`. `LabelExtent` is the
|
|
caller's measured label width/height. The node boxes and ranks are the landed
|
|
`GraphLayout` values; the router never moves or resizes a node.
|
|
|
|
`GraphRouting` exposes unmodifiable `routes`, `labels`, `skipped`, `width` and
|
|
`height`, plus `routeFor(id)` / `labelFor(id)`. Each `EdgeRoute` keeps the
|
|
definition `id`, `source`, `outcome`, `target`, `label` and `fallback` flag, and
|
|
returns `sourcePort`, `targetPort`, a `RouteKind` and an orthogonal `points`
|
|
list. Each `EdgeLabelBox` carries the measured box for its edge id.
|
|
|
|
## Deterministic guarantees (and what is not claimed)
|
|
|
|
- **Identity:** routed edges copy the definition identity unchanged; skipped
|
|
edges keep it in `RouteDiagnostic` with `unknownSource`/`unknownTarget`. No
|
|
node, route or visit is invented for an empty, missing or unknown target.
|
|
- **Order and stability:** routes, labels and diagnostics are ordered by edge id
|
|
regardless of input order. Equal input produces equal, immutable results.
|
|
- **Orthogonality and ports:** every consecutive point pair shares one
|
|
coordinate. Endpoints are exactly on the source/target border with the
|
|
recorded side: forward routes leave right and enter left; same-rank, backward
|
|
and self-loop routes leave/enter the right side.
|
|
- **Node avoidance:** a forward one-rank route is a straight horizontal run only
|
|
when the boxes share a port band and leave room for label-aware track spacing.
|
|
Every other route drops into a unique horizontal lane below the node grid,
|
|
travels vertically only inside column gaps (or the free space right of the
|
|
last column), and returns to a port through its own stub. Vertical corridors
|
|
and lanes never enter a node column, and every horizontal stub stays on a row
|
|
that is clear of unrelated node boxes.
|
|
- **Distinguishable runs:** vertical tracks are spread across each gap, one
|
|
slot per corridor request; horizontal stubs and straight routes share one
|
|
interval-aware allocator; every wrapping route owns its own lane. Two edges
|
|
cannot share a collinear run in the tested fixtures.
|
|
- **Labels:** each routed edge needs a measured `LabelExtent`; a missing one is
|
|
an `ArgumentError`. The box is placed at a deterministic route run, clear of
|
|
node interiors and earlier labels. If a run is too narrow (for example a wide
|
|
label between close columns), the label moves to a free shelf below the
|
|
drawing and the returned bounds grow instead of covering a node.
|
|
- **Bounds:** `width`/`height` include the landed node layout, all route points
|
|
and all label boxes, plus `boundsPadding`. A self loop or an edge into the
|
|
right-free gap expands the box; nothing is clipped.
|
|
- **Not claimed:** perfect general crossing minimization or minimal bend
|
|
counts. Corridors and lanes are deterministic and locally separated, not a
|
|
globally optimal routing.
|
|
|
|
## Checks actually run
|
|
|
|
```
|
|
flutter pub get
|
|
dart format lib/features/graph/routing test/features/graph/routing # 0 changed
|
|
flutter test test/features/graph/routing # 20 passed
|
|
flutter analyze # No issues found!
|
|
flutter test # 193 passed
|
|
```
|
|
|
|
Focused coverage includes chain, diamond fan-out/fan-in, three outcomes to one
|
|
target, a two-stage and a three-stage SCC, a self loop alone and beside forward
|
|
routes, disconnected stages, heterogeneous widths, 2.6x expanded text, tight
|
|
gaps, wide labels, a caller-supplied backward rank, missing/empty/unknown
|
|
targets, immutability, stable ordering and finite bounds.
|
|
|
|
## Honest limits
|
|
|
|
- **No rendering.** This is a nonvisual geometry slice: no painter, widgets,
|
|
native controls, screenshots or browser behavior. Rendered parity belongs to
|
|
the next renderer task.
|
|
- **Layout is an input.** The router does not widen columns for labels or move
|
|
nodes. Very wide labels may sit on the free shelf below the drawing; callers
|
|
that want labels beside an edge should reserve enough column gap when laying
|
|
out nodes. A zero-width column gap leaves no space for distinct vertical
|
|
corridors, so callers should supply a positive gap (the landed layout keeps
|
|
whatever gap it is given).
|
|
- **No general crossing optimum.** Only deterministic corridor/lane separation
|
|
is guaranteed, as described above.
|
|
- **No server or device.** Tests use local fixtures only; no run, pipeline,
|
|
schedule, service, emulator, ADB, Android/iOS build or live chat was touched.
|
|
- **Mobile unverified.** Only web-targeted Flutter test/analyze ran.
|
|
- **Uncommitted candidate.** Per this stage's instruction the slice is left in
|
|
the worktree; no commit, push or deployment was made.
|