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

4.8 KiB

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

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.