147 lines
8.5 KiB
Markdown
147 lines
8.5 KiB
Markdown
# P2-run-graph — executed vs unexecuted run evidence
|
|
|
|
## Scope
|
|
|
|
App-only, new files. No existing source, `main.dart`, shell, pubspec, server, web
|
|
client, platform directory or other feature lane was edited. The slice renders a
|
|
run definition with recorded execution evidence and reports a visited stage key
|
|
to its caller; it does not open the visit pane itself and is not wired into the
|
|
run tab (that integration belongs to the runs lane).
|
|
|
|
| File | Lines | Responsibility |
|
|
| --- | --- | --- |
|
|
| `lib/features/graph/widgets/run_graph_view.dart` | 331 | bounded widget, geometry, recorded evidence, legend/elapsed header |
|
|
| `lib/features/graph/widgets/run_graph_canvas.dart` | 367 | split edge layer/painter, canvas composition, native node wrapper, measurement |
|
|
| `test/features/graph/widgets/run_graph_view_test.dart` | 460 | evidence, route classes, terminal truth, click/semantics, empty state, order, 320/2x, dark Cupertino, status remeasure |
|
|
| `test/features/graph/widgets/run_graph_edge_layer_test.dart` | 147 | solid/arrowed taken strokes, dashed untaken strokes, passive hit test, repaint |
|
|
| `tool/run_graph_probe.dart` | 200 | isolated browser fixture (not app/shell registration) |
|
|
| `tool/run_graph_probe.mjs` | 265 | real-Chrome assertions and captures |
|
|
|
|
Both source files are cohesive units and slightly over the 250-line aim because
|
|
the view owns evidence/geometry while the helper owns painting/measurement and
|
|
the native node wrapper. Splitting further would either duplicate measurement or
|
|
create arbitrary fragments.
|
|
|
|
## Public API
|
|
|
|
```dart
|
|
RunGraphView(
|
|
graph: JsonMap?, // omitted run graph -> exact missing wording
|
|
run: JsonMap, // recorded steps are the only evidence
|
|
onStageSelected: ValueChanged<String>,
|
|
selectedStage: String?, // caller-owned graph selection
|
|
now: DateTime Function()?, // deterministic elapsed tests
|
|
)
|
|
```
|
|
|
|
`runGraphMissing` is the exact web sentence: `This server did not include the
|
|
run graph.` `runGraphExecuted` / `runGraphNotExecuted` are `Executed` and
|
|
`Not executed`.
|
|
|
|
## Behavior
|
|
|
|
- **Visited stages only:** `RunGraphState` decides visits and routes. A visited
|
|
stage's native node receives its latest recorded step status (sequence order,
|
|
via `visitsByStage`). An unvisited stage gets no status, no tap target and no
|
|
button semantics; it is a plain graph label. No visit, session, status or
|
|
elapsed value is fabricated.
|
|
- **Terminals:** only `RunGraphState.visitedStages` terminals (a recorded route
|
|
resolved there) show evidence, using the recorded route outcome
|
|
(`success`/`error`). An untaken terminal stays plain. Terminals own no recorded
|
|
step, so they are never presented as an openable visit.
|
|
- **Routes:** taken definition routes are solid and arrowed using the landed
|
|
`GraphEdgePainter` geometry; untaken routes are dashed, arrowless and use the
|
|
host's outline/separator role. Only taken routes get outcome labels, as in the
|
|
web run tab. Untaken routes keep their definition order and identifiers.
|
|
- **Order:** routing preserves `graphEdges` order, so a stage's outcomes are
|
|
success first, other alphabetical, error last. The run filter does not reorder
|
|
them.
|
|
- **Legend:** a native `Wrap` of two stock-icon entries, `Executed` and
|
|
`Not executed`, labelled `Route kinds` for assistive technology. No bespoke
|
|
palette or swatch painting.
|
|
- **Elapsed:** a static `Current stage <key> · elapsed <duration>` line appears
|
|
only while `RunGraphState.activeStage` exists (run executing). It is computed
|
|
once per build from `currentStageStartedAt`; there is no timer, pulse or
|
|
invented progress. With no parseable start it says only `Current stage <key>`.
|
|
- **Node styling:** Material uses the landed `Card`/`Card.filled` node and
|
|
Cupertino its tinted/filled buttons; the recorded-status line is the execution
|
|
affordance. Status changes drop only that node's stale measured extent, and the
|
|
measurement key includes the status so even a same-size status change reports
|
|
a fresh extent; a taller node is never placed in the old box.
|
|
- **Viewport:** the caller must supply bounded constraints; the view fills them
|
|
with stock `InteractiveViewer` pan/zoom (`minScale: 0.3`, `maxScale: 3`).
|
|
Node and label extents are measured from the exact widgets placed. At 320px
|
|
and 2x text the graph pans instead of shrinking or clipping content.
|
|
- **Empty:** null/absent graph or a graph with no stages shows the exact
|
|
`This server did not include the run graph.` sentence and no viewer.
|
|
|
|
## Checks actually run
|
|
|
|
```
|
|
dart format lib/features/graph/widgets test/features/graph/widgets tool/run_graph_probe.dart
|
|
flutter test test/features/graph/widgets/run_graph_view_test.dart \
|
|
test/features/graph/widgets/run_graph_edge_layer_test.dart # 13 passed
|
|
flutter test test/features/graph # 153 passed
|
|
flutter test # 844 passed
|
|
flutter analyze # No issues found!
|
|
flutter build web # ✓ Built build/web
|
|
flutter build web -t tool/run_graph_probe.dart -o build/run_graph_probe
|
|
```
|
|
|
|
The full-app `flutter analyze`, `flutter test` and `flutter build web` also pass;
|
|
integrated run-tab registration was not performed because the shell/runs wiring
|
|
belongs to another lane.
|
|
|
|
## Rendered evidence
|
|
|
|
Fresh real Chrome (headless, throwaway profile, loopback server on an
|
|
OS-assigned port). The fixture records a running `plan -> build` path and a
|
|
finished `plan -> build -> audit -> Success` path. Captures are in shared
|
|
`public/run-graph-captures/`:
|
|
|
|
| File | Shows |
|
|
| --- | --- |
|
|
| `run-graph-material-light-1x-running-initial.png` | visited plan/build with `completed`/`running`, solid arrowed taken route, dashed untaken routes, legend, live elapsed line |
|
|
| `run-graph-material-light-1x-running-final.png` | plan selected after a real node click; selection reported by key |
|
|
| `run-graph-material-light-1x-running-phone.png` | 320px material viewport |
|
|
| `run-graph-material-light-1x-finished-initial.png` | finished run: executed path through `Success success`, no live line, untaken failure route dashed |
|
|
| `run-graph-material-light-1x-finished-final.png` / `-phone.png` | final/phone variants after pan and terminal safety check |
|
|
| `run-graph-cupertino-dark-2x-running-initial.png` | dark Cupertino host at 320px/2x, wrapped native legend, visited statuses |
|
|
| `run-graph-cupertino-dark-2x-running-final.png` | real pan exposes the running build node |
|
|
| `run-graph-cupertino-dark-2x-finished-initial.png` / `-final.png` | dark Cupertino finished path and terminal evidence |
|
|
|
|
The probe asserts legend wording, visible recorded statuses, the live line only
|
|
for the running fixture, click-by-key selection, unvisited `audit` leaving
|
|
selection unchanged, a finished terminal click not creating a visit, and real
|
|
drag panning at 320/2x. Earlier `*-desktop.png` captures from the first probe
|
|
run were removed as superseded by the `initial`/`final` set.
|
|
|
|
## Honest limits
|
|
|
|
- **Not wired.** No run-tab, shell or application edit; the caller must supply
|
|
the graph/run maps and open the reported stage's latest recorded visit.
|
|
- **Terminal clicks do nothing.** Terminals have no recorded step, so the view
|
|
refuses to invent a visit for them; they remain evidence-only.
|
|
- **No live ticking.** The elapsed line is intentionally static per build; a
|
|
live ticking badge/timer remains for the integrating lane.
|
|
- **No browser keyboard/fit toolbar.** Standard node focus semantics come from
|
|
the native controls, but a fit/expand toolbar was not added (not in this
|
|
slice).
|
|
- **Mobile unverified.** Only Chrome/Flutter web was built and driven. Android
|
|
and iOS were not built, installed or tested.
|
|
- **Not committed.** The stage instruction forbids commit/push/deploy, so the
|
|
candidate remains uncommitted working-tree files; no main merge or push. The
|
|
task input's "commit the candidate" is superseded by the stage policy.
|
|
|
|
## Manager completion after an infrastructure failure
|
|
|
|
The run ended with the server's `UNIQUE constraint failed:
|
|
step_file_changes.run_id, step_file_changes.sequence (1555)` persistence bug, not
|
|
an app fault; the parallel search slice failed the same way. The retained work is
|
|
complete: the manager ran the graph widget suite (43 tests pass) and inspected the
|
|
run-mode canvas, then merged it. No retry of this slice was started. The server
|
|
defect is tracked in WORK.md and fixed separately with a regression.
|
|
|
|
This slice is the run-mode COMPONENT only: it is not yet the run detail's Graph
|
|
tab and does not open visit panes. Those remain wiring work.
|