From ddd8eacb1ffd1d97d9b8211bbfd67d16de2af18c Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 03:26:33 +0100 Subject: [PATCH] feat(app): show recorded session export state in visit pane --- .../runs/ui/run_detail_visit_session.dart | 71 ++++- .../ui/run_detail_visit_session_state.dart | 283 +++++++++++++++--- .../run_detail_visit_session_export_test.dart | 185 ++++++++++++ 3 files changed, 482 insertions(+), 57 deletions(-) create mode 100644 app/test/features/runs/ui/run_detail_visit_session_export_test.dart diff --git a/app/lib/features/runs/ui/run_detail_visit_session.dart b/app/lib/features/runs/ui/run_detail_visit_session.dart index 19268625..23dcccd1 100644 --- a/app/lib/features/runs/ui/run_detail_visit_session.dart +++ b/app/lib/features/runs/ui/run_detail_visit_session.dart @@ -8,12 +8,15 @@ import '../../artifacts/domain/artifact_url.dart'; import '../../artifacts/ui/artifact_external_open.dart'; import 'run_detail_visit_session_state.dart'; -/// The visit's recorded session pointer and, when the visit exported one, a -/// read-only external open of that document. +/// The visit's recorded session pointer, its recorded export state and, when +/// the visit exported one, a read-only external open of that document. /// /// The state comes from [detailVisitSession], so a legacy `session.html`, a /// repair, a still-running session and a failed one each report what the server -/// recorded. The open goes through the landed safe-link helper: the recorded url +/// recorded. Complete, partial, missing, skipped, repair and unrecognised +/// states each keep the server's own word and diagnostic; recorded repair +/// attempts and their open-option labels are shown read-only and make no +/// request. The open goes through the landed safe-link helper: the recorded url /// is resolved by [resolveArtifactUrl] and passed to [openArtifactExternally] /// without being fetched, rewritten or previewed. A refusal is reported. class RunVisitSession extends StatefulWidget { @@ -53,17 +56,34 @@ class _RunVisitSessionState extends State { ? null : resolveArtifactUrl(widget.configuredEndpoint, export.artifact.url); final note = export?.statusNote; + final fact = session.exportFact; + final showReason = + export != null && + fact?.reason != null && + fact!.state != VisitSessionExportState.repair; final children = [ if (session.sessionId != null) _SessionFact(label: 'Session', value: session.sessionId!), - if (export != null) ...[ - if (note != null) Text(note), - if (resolved == null) - const Text(visitSessionEndpointMissing) - else - _openButton(export.artifact, resolved), - ] else - Text(session.message), + if (fact != null) + _SessionFact( + key: const Key('run-visit-session-export'), + label: 'Export', + value: fact.word, + ), + if (showReason) + _SessionFact( + key: const Key('run-visit-session-export-reason'), + label: 'Reason', + value: fact!.reason!, + ), + if (export != null && note != null) Text(note), + ..._repairFacts(session.repairs), + if (export == null) + Text(session.message) + else if (resolved == null) + const Text(visitSessionEndpointMissing) + else + _openButton(export.artifact, resolved), if (_status != null) Padding( padding: const EdgeInsets.only(top: 8), @@ -110,6 +130,33 @@ class _RunVisitSessionState extends State { ); } + /// Recorded repair attempts, in the pane's own fact rows. Nothing here is a + /// control: the repair request belongs to its own action and is not wired. + List _repairFacts(List repairs) { + final facts = []; + for (var index = 0; index < repairs.length; index += 1) { + final repair = repairs[index]; + facts.add( + _SessionFact( + key: ValueKey('run-visit-session-repair-$index'), + label: 'Repair', + value: repair.label, + ), + ); + final option = repair.option; + if (option != null) { + facts.add( + _SessionFact( + key: ValueKey('run-visit-session-repair-option-$index'), + label: 'Repair option', + value: option, + ), + ); + } + } + return facts; + } + List _spaced(List children) => [ for (var index = 0; index < children.length; index += 1) ...[ if (index > 0) const SizedBox(height: 8), @@ -119,7 +166,7 @@ class _RunVisitSessionState extends State { } class _SessionFact extends StatelessWidget { - const _SessionFact({required this.label, required this.value}); + const _SessionFact({super.key, required this.label, required this.value}); final String label; final String value; diff --git a/app/lib/features/runs/ui/run_detail_visit_session_state.dart b/app/lib/features/runs/ui/run_detail_visit_session_state.dart index 0a980675..b902d785 100644 --- a/app/lib/features/runs/ui/run_detail_visit_session_state.dart +++ b/app/lib/features/runs/ui/run_detail_visit_session_state.dart @@ -3,9 +3,8 @@ import '../../artifacts/domain/artifact_record.dart'; import '../../artifacts/domain/artifact_selection.dart'; /// The exact wording for a visit that never started a harness session, in the -/// web audit pane's order: a skipped visit, a stopped one, a model visit whose -/// session is still being created, a failed one, and a model visit with no -/// identity at all. Only a non-model visit with nothing recorded gets the +/// web audit pane's order: skipped, stopped, being created, failed, and a model +/// visit with no identity. Only a non-model visit with nothing recorded gets the /// generic sentence. const String visitSessionSkipped = 'This visit was skipped; no harness session was started.'; @@ -21,6 +20,59 @@ const String visitSessionNone = 'This visit has no harness session.'; const String visitSessionEndpointMissing = 'Set the server URL in Settings to open the session.'; +/// The export state the pane reports. A status this client does not know is +/// [unknown] and is shown verbatim; it is never rounded to complete. +enum VisitSessionExportState { + complete, + partial, + missing, + skipped, + repair, + unknown, +} + +/// The one state line for a visit's recorded export, with the server's own +/// diagnostic as [reason] when it recorded one. +class VisitSessionExportFact { + const VisitSessionExportFact({ + required this.state, + required this.word, + this.reason, + }); + + final VisitSessionExportState state; + + /// The state word shown to the operator. An unknown status keeps the + /// server's exact word here instead of being mapped to a known state. + final String word; + + /// The server-recorded diagnostic, verbatim, or null when there was none. + final String? reason; +} + +/// One recorded repair attempt and the read-only labels the pane shows for it. +class VisitSessionRepair { + const VisitSessionRepair({ + required this.status, + required this.messages, + this.diagnostic, + this.option, + }); + + final String status; + final int messages; + final String? diagnostic; + + /// The web pane's open label, shown read-only, or null when this repair is + /// the document the main open action already points at. + final String? option; + + /// The web audit pane's repair label, without its `Repair: ` prefix. + String get label => + '$status · $messages messages.' + '${diagnostic == null ? '' : ' $diagnostic'}'; +} + /// A recorded session export document and the evidence the server recorded for /// it. class VisitSessionExport { @@ -28,60 +80,102 @@ class VisitSessionExport { required this.artifact, this.status, this.diagnostic, + this.messages = 0, + this.htmlBytes = 0, this.truncated = false, + this.repaired = false, }); final ArtifactRecord artifact; final String? status; final String? diagnostic; + final int messages; + final int htmlBytes; final bool truncated; - /// A partial or failed export is still the recorded document; it stays - /// openable and the pane says what the evidence reports. - bool get isComplete => status == 'complete' && !truncated; + /// True when the document is one of the visit's recorded repair attempts. + final bool repaired; - /// The evidence sentence shown beside a present but incomplete export, or - /// null when the export is complete or the visit recorded no evidence. + /// Completeness needs the server's complete status plus positive message and + /// byte counts, an untruncated document and no diagnostic. An absent or + /// partial record is never promoted to complete. + bool get isComplete => + status == 'complete' && + messages > 0 && + htmlBytes > 0 && + !truncated && + diagnostic == null; + + /// The evidence sentence beside a present but incomplete export, or null + /// when the export is complete or no evidence was recorded. String? get statusNote { if (isComplete) return null; - if (status == null && !truncated) return null; - return 'This export is ${status ?? 'partial'}; full session evidence is ' - 'not available.'; + if (status == null && messages <= 0 && !truncated) return null; + final word = status == null || status == 'complete' ? 'partial' : status; + return 'This export is $word; full session evidence is not available.'; } } -/// A visit's recorded session: its identity, an openable export document and, -/// when neither exists, the one sentence describing the recorded state. +/// A visit's recorded session: identity, openable export, recorded export +/// state, recorded repairs and, without a document, the recorded sentence. class VisitSessionState { - const VisitSessionState({this.sessionId, this.export, this.message = ''}); + const VisitSessionState({ + this.sessionId, + this.export, + this.message = '', + this.exportFact, + this.repairs = const [], + }); final String? sessionId; final VisitSessionExport? export; /// Empty exactly when [export] is present. final String message; + + /// Null when the visit recorded no session at all. + final VisitSessionExportFact? exportFact; + + /// Every recorded repair attempt, oldest first, read-only. + final List repairs; } /// Resolves the recorded session state without inventing a session. /// /// The export is looked up through the recorded export evidence (including a -/// repair that replaced it) and then, for a historical visit that recorded no -/// evidence at all, through the `session.html` its inventory carries. When the -/// evidence names no file, its own status and diagnostic are reported instead -/// of claiming the inventory is empty. +/// repair that replaced it) and then, for a historical visit with no evidence, +/// through its `session.html`. When the evidence names no file, its own status +/// and diagnostic are reported instead of claiming the inventory is empty. VisitSessionState detailVisitSession(JsonMap step) { final sessionId = detailVisitSessionIdentity(step); final export = detailVisitSessionExport(step); + final repairs = _repairs(step, export); if (export != null) { - return VisitSessionState(sessionId: sessionId, export: export); + return VisitSessionState( + sessionId: sessionId, + export: export, + exportFact: _exportFact(export), + repairs: repairs, + ); } if (sessionId != null) { return VisitSessionState( sessionId: sessionId, message: _missingExportMessage(step, sessionId), + exportFact: _missingFact(step), + repairs: repairs, ); } - return VisitSessionState(message: _noSessionMessage(step)); + return VisitSessionState( + message: _noSessionMessage(step), + exportFact: _isSkipped(step) + ? const VisitSessionExportFact( + state: VisitSessionExportState.skipped, + word: 'skipped', + ) + : null, + repairs: repairs, + ); } /// The recorded harness session identity, from the step or its export evidence. @@ -96,19 +190,21 @@ String? detailVisitSessionIdentity(JsonMap step) { /// is present in the inventory. /// /// The step's own `session_export` is preferred; a repair document is used -/// when that is the file the inventory actually carries. A visit with no export -/// evidence at all falls back to its `session.html` system artifact, exactly as -/// the web audit pane does for runs recorded before the evidence field existed. +/// when that is the file the inventory carries. A visit with no export evidence +/// falls back to its `session.html`, exactly as the web audit pane does. VisitSessionExport? detailVisitSessionExport(JsonMap step) { final evidence = _exportEvidence(step); for (final entry in evidence) { - final artifact = _artifactNamed(step, _text(entry['html'])); + final artifact = _artifactNamed(step, _text(entry.evidence['html'])); if (artifact == null) continue; return VisitSessionExport( artifact: artifact, - status: _text(entry['status']), - diagnostic: _text(entry['diagnostic']), - truncated: entry['truncated'] == true, + status: _text(entry.evidence['status']), + diagnostic: _text(entry.evidence['diagnostic']), + messages: _count(entry.evidence['messages']), + htmlBytes: _count(entry.evidence['html_bytes']), + truncated: entry.evidence['truncated'] == true, + repaired: entry.repaired, ); } if (evidence.isNotEmpty) return null; @@ -120,6 +216,99 @@ VisitSessionExport? detailVisitSessionExport(JsonMap step) { return null; } +VisitSessionExportFact _exportFact(VisitSessionExport export) { + if (export.repaired) { + return VisitSessionExportFact( + state: VisitSessionExportState.repair, + word: 'repair', + reason: export.diagnostic, + ); + } + final status = export.status; + if (status == 'complete') { + if (export.isComplete) { + return const VisitSessionExportFact( + state: VisitSessionExportState.complete, + word: 'complete', + ); + } + return _partialFact(export); + } + if (status == null) { + return VisitSessionExportFact( + state: VisitSessionExportState.unknown, + word: 'unknown', + reason: export.diagnostic, + ); + } + if (_partialStatuses.contains(status)) return _partialFact(export); + return VisitSessionExportFact( + state: VisitSessionExportState.unknown, + word: status, + reason: export.diagnostic, + ); +} + +VisitSessionExportFact _partialFact(VisitSessionExport export) => + VisitSessionExportFact( + state: VisitSessionExportState.partial, + word: 'partial', + reason: export.diagnostic, + ); + +VisitSessionExportFact _missingFact(JsonMap step) { + final evidence = _firstEvidence(step); + final status = evidence == null ? null : _text(evidence['status']); + final diagnostic = evidence == null ? null : _text(evidence['diagnostic']); + if (status != null && + status != 'complete' && + !_partialStatuses.contains(status)) { + return VisitSessionExportFact( + state: VisitSessionExportState.unknown, + word: status, + reason: diagnostic, + ); + } + return VisitSessionExportFact( + state: VisitSessionExportState.missing, + word: 'missing', + reason: diagnostic, + ); +} + +const Set _partialStatuses = { + 'partial', + 'empty', + 'failed', + 'truncated', + 'incomplete', + 'unavailable', +}; + +List _repairs(JsonMap step, VisitSessionExport? export) { + final recorded = step['session_export_repairs']; + if (recorded is! List) return const []; + final selectedName = export?.artifact.name; + final repairs = []; + for (final entry in recorded) { + if (entry is! Map) continue; + final artifact = _artifactNamed(step, _text(entry['html'])); + final selected = artifact != null && artifact.name == selectedName; + repairs.add( + VisitSessionRepair( + status: _text(entry['status']) ?? 'partial', + messages: _count(entry['messages']), + diagnostic: _text(entry['diagnostic']), + option: artifact == null || selected ? null : 'Open repaired export', + ), + ); + } + return repairs; +} + +bool _isSkipped(JsonMap step) => + _text(step['status']) == 'skipped' || _text(step['outcome']) == 'skipped'; + String _missingExportMessage(JsonMap step, String sessionId) { final evidence = _firstEvidence(step); final recovery = step['session_export_recovery']; @@ -140,9 +329,7 @@ String _missingExportMessage(JsonMap step, String sessionId) { String _noSessionMessage(JsonMap step) { final status = _text(step['status']); - if (status == 'skipped' || _text(step['outcome']) == 'skipped') { - return visitSessionSkipped; - } + if (_isSkipped(step)) return visitSessionSkipped; if (status == 'canceled' || status == 'interrupted') { return visitSessionStopped; } @@ -162,7 +349,7 @@ String _noSessionMessage(JsonMap step) { /// complete original, then every remaining candidate. A failed later attempt /// never hides an earlier verified document; an older original never hides the /// repair that replaced it. -List _exportEvidence(JsonMap step) { +List<_RecordedExport> _exportEvidence(JsonMap step) { final repairs = []; final recordedRepairs = step['session_export_repairs']; if (recordedRepairs is List) { @@ -171,25 +358,32 @@ List _exportEvidence(JsonMap step) { } } final original = step['session_export']; - final ordered = []; - void add(Map entry) { + final ordered = <_RecordedExport>[]; + void add(Map entry, bool repaired) { for (final candidate in ordered) { - if (identical(candidate, entry)) return; + if (identical(candidate.evidence, entry)) return; } - ordered.add(entry); + ordered.add(_RecordedExport(entry, repaired)); } for (final repair in repairs) { - if (_isComplete(repair)) add(repair); + if (_isComplete(repair)) add(repair, true); } - if (original is Map && _isComplete(original)) add(original); + if (original is Map && _isComplete(original)) add(original, false); for (final repair in repairs) { - add(repair); + add(repair, true); } - if (original is Map) add(original); + if (original is Map) add(original, false); return ordered; } +class _RecordedExport { + const _RecordedExport(this.evidence, this.repaired); + + final Map evidence; + final bool repaired; +} + Map? _firstEvidence(JsonMap step) { final original = step['session_export']; if (original is Map) return original; @@ -204,15 +398,14 @@ Map? _firstEvidence(JsonMap step) { bool _isComplete(Map evidence) => _text(evidence['status']) == 'complete' && - _positive(evidence['messages']) && - _positive(evidence['html_bytes']) && + _count(evidence['messages']) > 0 && + _count(evidence['html_bytes']) > 0 && evidence['truncated'] != true && _text(evidence['diagnostic']) == null; -bool _positive(dynamic value) { - if (value is num) return value > 0; - if (value is String) return (int.tryParse(value.trim()) ?? 0) > 0; - return false; +int _count(dynamic value) { + if (value is num) return value.toInt(); + return int.tryParse('${value ?? ''}'.trim()) ?? 0; } ArtifactRecord? _artifactNamed(JsonMap step, String? name) { diff --git a/app/test/features/runs/ui/run_detail_visit_session_export_test.dart b/app/test/features/runs/ui/run_detail_visit_session_export_test.dart new file mode 100644 index 00000000..866c0c73 --- /dev/null +++ b/app/test/features/runs/ui/run_detail_visit_session_export_test.dart @@ -0,0 +1,185 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/runs/ui/run_detail_visit_session.dart'; +import 'package:pipelines_app/features/runs/ui/run_detail_visit_session_state.dart'; + +import 'run_detail_visit_support.dart'; + +Future pumpSessionExport(WidgetTester tester, JsonMap step) => + tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: RunVisitSession( + step: step, + configuredEndpoint: 'ws://example.test/connect', + ), + ), + ), + ); + +JsonMap sessionStep() => firstVisitStep(visitRunFixture()); + +JsonMap artifact(String name) => { + 'name': name, + 'url': 'https://example.test/artifacts/$name', + 'content_type': 'text/html', + 'size_bytes': 100, +}; + +void main() { + testWidgets('a verified export reports complete', (tester) async { + await pumpSessionExport(tester, sessionStep()); + + expect(find.text('complete'), findsOneWidget); + expect(find.text('partial'), findsNothing); + expect(find.textContaining('full session evidence'), findsNothing); + expect(find.text('Reason'), findsNothing); + }); + + testWidgets('a partial export keeps the server status and its reason', ( + tester, + ) async { + final step = sessionStep(); + step['session_export'] = { + 'html': 'session.html', + 'status': 'failed', + 'messages': 2, + 'diagnostic': 'The native read was refused.', + }; + await pumpSessionExport(tester, step); + + expect(find.text('partial'), findsOneWidget); + expect( + find.textContaining( + 'This export is failed; full session evidence is not available.', + ), + findsOneWidget, + ); + expect(find.text('The native read was refused.'), findsOneWidget); + }); + + testWidgets('complete status without evidence is not promoted to complete', ( + tester, + ) async { + final step = sessionStep(); + step['session_export'] = { + 'html': 'session.html', + 'status': 'complete', + 'messages': 0, + 'html_bytes': 0, + 'diagnostic': 'Bounded read returned no messages.', + }; + await pumpSessionExport(tester, step); + + expect(find.text('complete'), findsNothing); + expect(find.text('partial'), findsOneWidget); + expect(find.text('Bounded read returned no messages.'), findsOneWidget); + }); + + testWidgets('an export with no recorded evidence stays unknown', ( + tester, + ) async { + final step = sessionStep()..remove('session_export'); + await pumpSessionExport(tester, step); + + expect(find.text('unknown'), findsOneWidget); + expect(find.text('complete'), findsNothing); + }); + + testWidgets('a missing export reports missing and the server reason', ( + tester, + ) async { + final step = sessionStep(); + step['session_export'] = { + 'html': 'session.html', + 'status': 'failed', + 'diagnostic': 'The export file was not listed.', + }; + step['artifacts'] = [artifact('plan.csv')]; + await pumpSessionExport(tester, step); + + expect(find.text('missing'), findsOneWidget); + expect( + find.textContaining('The export file was not listed.'), + findsOneWidget, + ); + expect(find.textContaining('Open '), findsNothing); + }); + + testWidgets('a skipped visit reports skipped and its recorded sentence', ( + tester, + ) async { + final step = sessionStep(); + step['status'] = 'skipped'; + step['outcome'] = 'skipped'; + step + ..remove('session_id') + ..remove('session_export') + ..remove('artifacts'); + await pumpSessionExport(tester, step); + + expect(find.text('skipped'), findsOneWidget); + expect(find.text(visitSessionSkipped), findsOneWidget); + }); + + testWidgets('recorded repairs and their open labels stay read-only', ( + tester, + ) async { + final step = sessionStep(); + step['session_export'] = { + 'html': 'session.html', + 'status': 'failed', + 'messages': 0, + 'diagnostic': 'The first export failed.', + }; + step['session_export_repairs'] = [ + { + 'html': 'session-repair-1.html', + 'status': 'failed', + 'messages': 0, + 'diagnostic': 'The first repair failed.', + }, + { + 'html': 'session-repair-2.html', + 'status': 'complete', + 'messages': 3, + 'html_bytes': 500, + }, + ]; + step['artifacts'] = [ + artifact('plan.csv'), + artifact('session.html'), + artifact('session-repair-1.html'), + artifact('session-repair-2.html'), + ]; + await pumpSessionExport(tester, step); + + expect(find.text('repair'), findsOneWidget); + expect( + find.text('failed · 0 messages. The first repair failed.'), + findsOneWidget, + ); + expect(find.text('complete · 3 messages.'), findsOneWidget); + expect(find.text('Open repaired export'), findsOneWidget); + expect( + find.widgetWithText(TextButton, 'Open repaired export'), + findsNothing, + ); + expect(find.text('Open session-repair-2.html'), findsOneWidget); + }); + + testWidgets('an unrecognised export status is kept verbatim', (tester) async { + final step = sessionStep(); + step['session_export'] = { + 'html': 'session.html', + 'status': 'quarantined', + 'diagnostic': 'The server quarantined this export.', + }; + await pumpSessionExport(tester, step); + + expect(find.text('quarantined'), findsOneWidget); + expect(find.text('complete'), findsNothing); + expect(find.text('The server quarantined this export.'), findsOneWidget); + }); +}