Files
pipelines/app/notes/P2b.md
T
alan c1f140bc78 feat(app): add deterministic content-sized graph node layout
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.
2026-10-21 16:25:17 +01:00

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.