2c105074aa
Pure-Dart graph foundation mirroring the current web client: terminal targets and labels, definition edges and nodes with web outcome ordering, recorded run evidence (visited stages, taken routes, current stage and live start), and sequence-ordered stage visit selection with clamping. No layout, widgets, screens or coordinates; fixtures cover linear, diamond, self-loop, repeated visits, mixed outcomes, terminals and missing/malformed evidence.
153 lines
5.3 KiB
Dart
153 lines
5.3 KiB
Dart
import 'graph_protocol.dart';
|
|
|
|
/// The graph definition: nodes and edges declared by a pipeline, never the
|
|
/// evidence that a run executed them. Run evidence lives in
|
|
/// `run_graph_state.dart`; keeping the two shapes separate means a definition
|
|
/// can be drawn without claiming a visit happened.
|
|
///
|
|
/// Mirrors `stageOutcomes`, `edgeLabel`, `graphEdges` and `nodeDisplayLabel`
|
|
/// from `web/src/graph.js` (and `web/src/runDetail.js`). Pure data only.
|
|
|
|
/// Ordering priority: success first, error last, every other outcome
|
|
/// alphabetical in between (the web client's `outcomePriority`).
|
|
int _outcomePriority(String outcome) {
|
|
if (outcome == 'success') return 0;
|
|
if (outcome == 'error') return 2;
|
|
return 1;
|
|
}
|
|
|
|
/// A stage's edge outcomes in the app's one stable order.
|
|
List<String> stageOutcomes(dynamic stage) {
|
|
final edges = stage is Map ? stage['edges'] : null;
|
|
if (edges is! Map) return const <String>[];
|
|
final outcomes = edges.keys.map((key) => '$key').toList();
|
|
outcomes.sort((a, b) {
|
|
final priority = _outcomePriority(a) - _outcomePriority(b);
|
|
return priority != 0 ? priority : a.compareTo(b);
|
|
});
|
|
return outcomes;
|
|
}
|
|
|
|
/// The outcome label on an edge: `error*` for an implicit fallback error route.
|
|
String edgeLabel(dynamic stage, String outcome) {
|
|
final implicitFallback = stage is Map && stage['fallback_error'] == true;
|
|
return outcome == 'error' && implicitFallback ? 'error*' : outcome;
|
|
}
|
|
|
|
/// One declared edge, in stable definition order.
|
|
class GraphEdge {
|
|
const GraphEdge({
|
|
required this.id,
|
|
required this.source,
|
|
required this.outcome,
|
|
required this.target,
|
|
required this.label,
|
|
required this.fallback,
|
|
required this.knownTarget,
|
|
});
|
|
|
|
/// The 1-based id assigned in stable definition order (`Graph.edges()`).
|
|
final int id;
|
|
final String source;
|
|
final String outcome;
|
|
|
|
/// The resolved target: `#` has already become `#success`/`#failure`.
|
|
final String target;
|
|
final String label;
|
|
|
|
/// True only for the parser's implicit `error -> #failure` route.
|
|
final bool fallback;
|
|
|
|
/// True when [target] is a terminal or a stage declared in this graph.
|
|
///
|
|
/// An empty or unknown target is kept exactly as recorded, with this flag
|
|
/// false, so callers can show it honestly instead of inventing a node.
|
|
final bool knownTarget;
|
|
|
|
bool get isTerminal => isTerminalTarget(target);
|
|
}
|
|
|
|
/// One graph definition node: a declared stage, or a terminal the definition
|
|
/// routes to.
|
|
class GraphNode {
|
|
const GraphNode({required this.key, required this.terminal, this.stageIndex});
|
|
|
|
final String key;
|
|
final bool terminal;
|
|
|
|
/// The node's stage declaration index, or null for a terminal.
|
|
final int? stageIndex;
|
|
|
|
String get label => nodeDisplayLabel(key);
|
|
String get shortLabel => nodeLabel(key);
|
|
}
|
|
|
|
List<Map<String, dynamic>> _stages(dynamic graph) {
|
|
if (graph is! Map) return const <Map<String, dynamic>>[];
|
|
final stages = graph['stages'];
|
|
if (stages is! List) return const <Map<String, dynamic>>[];
|
|
return stages.whereType<Map>().map(Map<String, dynamic>.from).toList();
|
|
}
|
|
|
|
String _stageKey(Map<String, dynamic> stage) => '${stage['key'] ?? ''}';
|
|
|
|
/// Every definition edge in stable id order.
|
|
///
|
|
/// Stages keep declaration order and each stage's outcomes use
|
|
/// [stageOutcomes]; ids are contiguous in that order. An absent (null) edge
|
|
/// value declares no edge and is skipped, while an empty or unknown target is
|
|
/// preserved with [GraphEdge.knownTarget] false.
|
|
List<GraphEdge> graphEdges(dynamic graph) {
|
|
final stages = _stages(graph);
|
|
final stageKeys = <String>{
|
|
for (final stage in stages)
|
|
if (_stageKey(stage).isNotEmpty) _stageKey(stage),
|
|
};
|
|
final result = <GraphEdge>[];
|
|
for (final stage in stages) {
|
|
final edges = stage['edges'];
|
|
if (edges is! Map) continue;
|
|
final source = _stageKey(stage);
|
|
for (final outcome in stageOutcomes(stage)) {
|
|
final raw = edges[outcome];
|
|
if (raw == null) continue;
|
|
final target = resolveTarget(outcome, '$raw') ?? '';
|
|
result.add(
|
|
GraphEdge(
|
|
id: result.length + 1,
|
|
source: source,
|
|
outcome: outcome,
|
|
target: target,
|
|
label: edgeLabel(stage, outcome),
|
|
fallback: outcome == 'error' && stage['fallback_error'] == true,
|
|
knownTarget: isTerminalTarget(target) || stageKeys.contains(target),
|
|
),
|
|
);
|
|
}
|
|
}
|
|
return result;
|
|
}
|
|
|
|
/// The definition's nodes in declaration order.
|
|
///
|
|
/// A stage key identifies one node even when it is declared twice; self edges
|
|
/// and loops therefore never duplicate identity. Terminal nodes are appended
|
|
/// failure first, then success, once any declared edge resolves to a terminal
|
|
/// (the same `hasTerminal` rule the web layout uses). They are still
|
|
/// definition nodes, not evidence that a run reached them.
|
|
List<GraphNode> graphNodes(dynamic graph) {
|
|
final stages = _stages(graph);
|
|
final seen = <String>{};
|
|
final nodes = <GraphNode>[];
|
|
for (var index = 0; index < stages.length; index += 1) {
|
|
final key = _stageKey(stages[index]);
|
|
if (key.isEmpty || !seen.add(key)) continue;
|
|
nodes.add(GraphNode(key: key, terminal: false, stageIndex: index));
|
|
}
|
|
if (graphEdges(graph).any((edge) => edge.isTerminal)) {
|
|
nodes.add(const GraphNode(key: failureEnd, terminal: true));
|
|
nodes.add(const GraphNode(key: successEnd, terminal: true));
|
|
}
|
|
return nodes;
|
|
}
|