Files
pipelines/app/lib/features/graph/domain/graph_definition.dart
T
alan 2c105074aa feat(app): add graph domain model for runs and definitions
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.
2026-10-21 15:31:43 +01:00

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;
}