c1f140bc78
Pure-Dart SCC ranking and column placement over the landed graph identities. Every extent and gap is caller supplied; missing measurements are rejected rather than defaulted. Focused tests cover linear, diamond, cycle, self-loop, disconnected, terminal, expanded-text and invalid-input cases.
101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
# P2b — deterministic pure node layout
|
|
|
|
## What changed
|
|
|
|
New app-only, pure-Dart files. No existing file, server, web client, legacy
|
|
client, shell, `main.dart`, pubspec, other feature or platform source was edited.
|
|
|
|
| File | Lines | Responsibility |
|
|
| --- | --- | --- |
|
|
| `lib/features/graph/layout/layout_models.dart` | 127 | measured extents, gap config, immutable node box, layout + ranks |
|
|
| `lib/features/graph/layout/graph_ranks.dart` | 191 | deterministic SCC ranks over the landed definition nodes/edges |
|
|
| `lib/features/graph/layout/graph_node_layout.dart` | 142 | column/row placement, bounds, validation |
|
|
| `test/features/graph/layout/layout_fixtures.dart` | 102 | shared definitions and measured extents |
|
|
| `test/features/graph/layout/graph_ranks_test.dart` | 116 | linear/diamond/cycle/self-loop/disconnected/unknown/long-chain ranks |
|
|
| `test/features/graph/layout/graph_node_layout_test.dart` | 224 | ordering, terminals, heterogeneous and expanded extents, bounds, determinism |
|
|
| `test/features/graph/layout/graph_layout_validation_test.dart` | 96 | empty input, missing/extra measurements, duplicate keys, invalid sizes |
|
|
|
|
No layout widgets, painters, edge routing, styling or shell wiring were added.
|
|
|
|
## Public API
|
|
|
|
```dart
|
|
GraphRanks assignGraphRanks(List<GraphNode> nodes, List<GraphEdge> edges);
|
|
|
|
GraphLayout layoutGraphNodes({
|
|
required List<GraphNode> nodes,
|
|
required List<GraphEdge> edges,
|
|
required Map<String, NodeExtent> extents,
|
|
required GraphLayoutConfig config,
|
|
});
|
|
```
|
|
|
|
`NodeExtent` is the caller's measured width/height after text layout.
|
|
`GraphLayoutConfig` takes `columnGap`, `rowGap` and an optional outer `padding`.
|
|
No node size, font, colour or device value is assumed in the library.
|
|
|
|
`GraphLayout` returns an unmodifiable `nodes` list of `GraphNodeBox`
|
|
(`key`, `terminal`, `stageIndex`, `rank`, `x`, `y`, `width`, `height`), an
|
|
unmodifiable `ranks` map, `rankCount`, and total `width`/`height` including
|
|
padding. Node keys, terminal flags and stage indices are copied from the
|
|
landed `graphNodes` identities unchanged.
|
|
|
|
## Ranking behavior
|
|
|
|
Ranks are read from the definition supplied by the caller; the existing
|
|
`graphNodes`/`graphEdges` helpers remain the source of identities.
|
|
|
|
- Iterative Tarjan strongly connected components (no recursion; a 2000-stage
|
|
chain is covered), then longest-path ranks over the condensation DAG.
|
|
- Every member of a cycle shares one rank, so cyclic routes cannot recurse or
|
|
push members apart. Self loops are internal supervision and add no rank.
|
|
- Disconnected stages and disconnected terminals stay at rank 0.
|
|
- Edges whose source or target is not a node are ignored. An unknown or empty
|
|
target never creates a node or a rank.
|
|
- Ranking is linear in nodes plus edges and stable for repeated input.
|
|
|
|
## Placement behavior
|
|
|
|
- One column per rank; nodes keep definition order inside a rank.
|
|
- A column is as wide as its widest measured node; columns are separated by
|
|
`columnGap` and top-aligned.
|
|
- Nodes are centred in their column and stacked with exactly `rowGap` between
|
|
measured boxes (centres are compared in the heterogeneous test).
|
|
- Supplied widths/heights are placed verbatim, so expanded text is never
|
|
clipped to a fixed box; growing the extents grows the total bounds.
|
|
- Bounds include every box: tests assert `right <= width` and
|
|
`bottom <= height` for every fixture.
|
|
- The result is immutable and identical for identical input.
|
|
|
|
Measurements are required for every node; a missing key throws
|
|
`ArgumentError` rather than inventing a default size. Extra measurements are
|
|
ignored because they cannot become nodes. Duplicate/empty node keys, negative
|
|
or non-finite gaps and extents are rejected.
|
|
|
|
## Checks actually run
|
|
|
|
```
|
|
flutter pub get
|
|
dart format lib/features/graph/layout test/features/graph/layout
|
|
flutter test test/features/graph/layout # 21 passed
|
|
flutter analyze # No issues found!
|
|
flutter test # 173 passed
|
|
git diff --check # clean
|
|
```
|
|
|
|
Tests cover linear, diamond, cycle, self-loop, disconnected, terminals,
|
|
unknown/empty targets, heterogeneous extents, 2.6x expanded text, determinism,
|
|
bounds and invalid input.
|
|
|
|
## Honest limits
|
|
|
|
- **Nodes only.** Edge routing, ports, labels, lanes, hit testing, selection
|
|
highlighting, painting and native controls are separate later items.
|
|
- **Not rendered.** A pure nonvisual slice has no browser behavior to capture;
|
|
no screenshot or browser check applies.
|
|
- **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.
|