From cbba026cdc8172774539003d91a664ed3bf001d8 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 02:18:44 +0100 Subject: [PATCH] feat(app): resolve recorded search hits to their exact targets Map every recorded search hit payload (pipeline, version, run, step, field, artifact) to the server's own target token and accept that token back, so a result can name the exact entity it opened. A hit whose payload or recorded token is incomplete or disagreeing is reported as unresolved rather than guessed. --- .../features/search/domain/search_target.dart | 310 ++++++++++++++++++ .../features/search/search_target_test.dart | 218 ++++++++++++ 2 files changed, 528 insertions(+) create mode 100644 app/lib/features/search/domain/search_target.dart create mode 100644 app/test/features/search/search_target_test.dart diff --git a/app/lib/features/search/domain/search_target.dart b/app/lib/features/search/domain/search_target.dart new file mode 100644 index 00000000..bd3b1003 --- /dev/null +++ b/app/lib/features/search/domain/search_target.dart @@ -0,0 +1,310 @@ +import '../../../core/api_gateway.dart'; + +/// The kind of recorded entity a resolved target names. +enum SearchTargetKind { pipeline, version, run, step, field, artifact } + +/// The exact identity behind a recorded search hit. +/// +/// [wire] is the server's own stable target token +/// (`internal/protocol/search.go`): `pipeline:`, `pipeline::v`, +/// `run:`, `run::`, `run:::` or the +/// recorded artifact URL. It is derived from the typed payload, never copied +/// from the hit, and [SearchTarget.fromWire] accepts it back. +/// +/// The token is the identity: two targets that serialise to the same token are +/// the same target even when one of them also carries recorded visit facts the +/// token does not encode. A hit without an identity in its payload is reported +/// as [UnresolvedSearchTarget] by [searchTargetFor]; the client never guesses. +sealed class SearchTarget { + const SearchTarget(); + + SearchTargetKind get kind; + + /// The server's target token for this identity. + String get wire; + + /// Parses a server target token, or null when it names no known target. + /// + /// A token carries only identity, so a parsed step or artifact target has no + /// recorded stage/visit facts; those are payload extras, not identity. + static SearchTarget? fromWire(String wire) { + final token = wire.trim(); + if (token.isEmpty) return null; + + final pipeline = RegExp( + r'^pipeline:([0-9]+)(?::v([0-9]+))?$', + ).firstMatch(token); + if (pipeline != null) { + final id = _positive(pipeline.group(1)); + if (id == null) return null; + final version = pipeline.group(2); + if (version == null) return SearchPipelineTarget(id); + final parsed = _positive(version); + return parsed == null ? null : SearchVersionTarget(id, parsed); + } + + final run = RegExp(r'^run:([0-9]+)(?::(.+))?$').firstMatch(token); + if (run != null) { + final runId = _positive(run.group(1)); + if (runId == null) return null; + final rest = run.group(2); + if (rest == null) return SearchRunTarget(runId); + final parts = rest.split(':'); + if (parts.length > 2) return null; + final sequence = _positive(parts.first); + if (sequence == null) return null; + if (parts.length == 1) return SearchStepTarget(runId, sequence); + final field = parts.last; + return field.trim().isEmpty + ? null + : SearchFieldTarget(runId, sequence, field); + } + + // The server's artifact target is its own relative file URL + // (`/artifacts///`); an absolute form is accepted only when + // it carries that same path. + if (token.startsWith('/artifacts/')) return SearchArtifactTarget(token); + if (token.startsWith('http://') || token.startsWith('https://')) { + final uri = Uri.tryParse(token); + if (uri != null && uri.path.startsWith('/artifacts/')) { + return SearchArtifactTarget(token); + } + } + return null; + } + + @override + bool operator ==(Object other) => other is SearchTarget && other.wire == wire; + + @override + int get hashCode => wire.hashCode; + + @override + String toString() => wire; +} + +/// A pipeline identity hit: the pipeline's detail, always at its latest version. +final class SearchPipelineTarget extends SearchTarget { + const SearchPipelineTarget(this.pipelineId); + + final int pipelineId; + + @override + SearchTargetKind get kind => SearchTargetKind.pipeline; + + @override + String get wire => 'pipeline:$pipelineId'; +} + +/// A pipeline version hit: one exact recorded definition. +final class SearchVersionTarget extends SearchTarget { + const SearchVersionTarget(this.pipelineId, this.version); + + final int pipelineId; + final int version; + + @override + SearchTargetKind get kind => SearchTargetKind.version; + + @override + String get wire => 'pipeline:$pipelineId:v$version'; +} + +/// A run identity hit. +final class SearchRunTarget extends SearchTarget { + const SearchRunTarget(this.runId); + + final int runId; + + @override + SearchTargetKind get kind => SearchTargetKind.run; + + @override + String get wire => 'run:$runId'; +} + +/// A recorded step/visit hit. [stage] and [visit] are the visit facts the +/// payload records ([visit] is the server's visit number, not the zero-based +/// pane index); the server's token only names the run and sequence. +final class SearchStepTarget extends SearchTarget { + const SearchStepTarget(this.runId, this.sequence, {this.stage, this.visit}); + + final int runId; + final int sequence; + final String? stage; + final int? visit; + + @override + SearchTargetKind get kind => SearchTargetKind.step; + + @override + String get wire => 'run:$runId:$sequence'; +} + +/// A text hit inside one recorded step field. +final class SearchFieldTarget extends SearchTarget { + const SearchFieldTarget(this.runId, this.sequence, this.field); + + final int runId; + final int sequence; + final String field; + + @override + SearchTargetKind get kind => SearchTargetKind.field; + + @override + String get wire => 'run:$runId:$sequence:$field'; +} + +/// A recorded artifact hit. The recorded URL is the identity; [runId] and +/// [sequence] locate the visit that produced it. +final class SearchArtifactTarget extends SearchTarget { + const SearchArtifactTarget(this.url, {this.runId, this.sequence}); + + final String url; + final int? runId; + final int? sequence; + + @override + SearchTargetKind get kind => SearchTargetKind.artifact; + + @override + String get wire => url; +} + +/// Either the exact [SearchTarget] a hit names, or the reason it names none. +sealed class SearchTargetResolution { + const SearchTargetResolution(); +} + +final class ResolvedSearchTarget extends SearchTargetResolution { + const ResolvedSearchTarget(this.target); + + final SearchTarget target; +} + +final class UnresolvedSearchTarget extends SearchTargetResolution { + const UnresolvedSearchTarget(this.reason); + + /// Why the hit cannot be resolved, for the caller's own reporting. It is not + /// operator-facing copy. + final String reason; +} + +/// Maps the typed payload of one recorded search hit to its exact identity. +/// +/// Payload keys are checked in the same order as the landed row model, so a hit +/// resolves to the target its visible row describes. The server's recorded +/// token must also be present and equal the serialised identity: a hit without +/// a token is unresolvable, consistent with the landed row model marking such a +/// row read-only, and a token that disagrees with its payload is refused rather +/// than guessed. Unknown payloads, and a payload missing any part of its +/// identity (an id, a sequence, a field name or an artifact URL), are +/// [UnresolvedSearchTarget]. +SearchTargetResolution searchTargetFor(JsonMap hit) { + final identity = _identityFor(hit); + if (identity is UnresolvedSearchTarget) return identity; + final target = (identity as ResolvedSearchTarget).target; + + final recorded = _text(hit['target']); + if (recorded == null) { + return const UnresolvedSearchTarget('recorded target is missing'); + } + if (recorded != target.wire) { + return const UnresolvedSearchTarget( + 'recorded target does not match its payload', + ); + } + return ResolvedSearchTarget(target); +} + +SearchTargetResolution _identityFor(JsonMap hit) { + final pipeline = _payload(hit, 'pipeline'); + if (pipeline != null) { + final id = _positive(pipeline['id']); + if (id == null) { + return const UnresolvedSearchTarget('pipeline identity is missing'); + } + return ResolvedSearchTarget(SearchPipelineTarget(id)); + } + + final version = _payload(hit, 'version'); + if (version != null) { + final pipelineId = _positive(version['pipeline_id']); + final number = _positive(version['version']); + if (pipelineId == null || number == null) { + return const UnresolvedSearchTarget('version identity is incomplete'); + } + return ResolvedSearchTarget(SearchVersionTarget(pipelineId, number)); + } + + final run = _payload(hit, 'run'); + if (run != null) { + final id = _positive(run['id']); + if (id == null) { + return const UnresolvedSearchTarget('run identity is missing'); + } + return ResolvedSearchTarget(SearchRunTarget(id)); + } + + final step = _payload(hit, 'step'); + if (step != null) { + final runId = _positive(step['run_id']); + final sequence = _positive(step['sequence']); + if (runId == null || sequence == null) { + return const UnresolvedSearchTarget('step identity is incomplete'); + } + final visit = _positive(step['visit']); + final stage = _text(step['stage']); + return ResolvedSearchTarget( + SearchStepTarget(runId, sequence, stage: stage, visit: visit), + ); + } + + final field = _payload(hit, 'field'); + if (field != null) { + final runId = _positive(field['run_id']); + final sequence = _positive(field['sequence']); + final name = _text(field['field']); + if (runId == null || sequence == null || name == null) { + return const UnresolvedSearchTarget('field identity is incomplete'); + } + return ResolvedSearchTarget(SearchFieldTarget(runId, sequence, name)); + } + + final artifact = _payload(hit, 'artifact'); + if (artifact != null) { + final url = _text(artifact['url']); + if (url == null) { + return const UnresolvedSearchTarget('artifact url is missing'); + } + return ResolvedSearchTarget( + SearchArtifactTarget( + url, + runId: _positive(artifact['run_id']), + sequence: _positive(artifact['sequence']), + ), + ); + } + + return const UnresolvedSearchTarget('no recorded target payload'); +} + +Map? _payload(JsonMap hit, String key) { + final value = hit[key]; + return value is Map ? Map.from(value) : null; +} + +int? _positive(Object? value) { + final number = value is int + ? value + : value is num + ? value.toInt() + : int.tryParse('${value ?? ''}'); + return number != null && number > 0 ? number : null; +} + +String? _text(Object? value) { + final text = '${value ?? ''}'; + return text.trim().isEmpty ? null : text; +} diff --git a/app/test/features/search/search_target_test.dart b/app/test/features/search/search_target_test.dart new file mode 100644 index 00000000..a6eba452 --- /dev/null +++ b/app/test/features/search/search_target_test.dart @@ -0,0 +1,218 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/search/domain/search_target.dart'; + +JsonMap pipelineHit([JsonMap overrides = const {}]) => { + 'kind': 'pipeline', + 'target': 'pipeline:7', + 'pipeline': { + 'id': 7, + 'name': 'release', + 'version': 3, + 'stages': 4, + ...overrides, + }, +}; + +JsonMap versionHit([JsonMap overrides = const {}]) => { + 'kind': 'version', + 'target': 'pipeline:9:v2', + 'version': { + 'pipeline_id': 9, + 'version': 2, + 'content_hash': 'abc', + 'created_at': '2026-01-01T00:00:00Z', + ...overrides, + }, +}; + +JsonMap runHit([JsonMap overrides = const {}]) => { + 'kind': 'run', + 'target': 'run:11', + 'run': { + 'id': 11, + 'pipeline_name': 'release', + 'status': 'succeeded', + ...overrides, + }, +}; + +JsonMap stepHit([JsonMap overrides = const {}]) => { + 'kind': 'step', + 'target': 'run:11:4', + 'step': { + 'run_id': 11, + 'sequence': 4, + 'stage': 'builder', + 'visit': 2, + 'outcome': 'success', + ...overrides, + }, +}; + +JsonMap fieldHit([JsonMap overrides = const {}]) => { + 'kind': 'field', + 'target': 'run:11:4:output', + 'matched_field': 'output', + 'field': { + 'run_id': 11, + 'sequence': 4, + 'field': 'output', + 'snippet': 'the release is ready', + ...overrides, + }, +}; + +JsonMap artifactHit([JsonMap overrides = const {}]) => { + 'kind': 'artifact', + 'target': '/artifacts/11/4/notes.md', + 'artifact': { + 'run_id': 11, + 'sequence': 4, + 'name': 'notes.md', + 'content_type': 'text/markdown', + 'size_bytes': 2048, + 'url': '/artifacts/11/4/notes.md', + ...overrides, + }, +}; + +SearchTarget resolved(JsonMap hit) { + final resolution = searchTargetFor(hit); + expect(resolution, isA(), reason: '$hit'); + return (resolution as ResolvedSearchTarget).target; +} + +UnresolvedSearchTarget unresolved(JsonMap hit) { + final resolution = searchTargetFor(hit); + expect(resolution, isA(), reason: '$hit'); + return resolution as UnresolvedSearchTarget; +} + +void main() { + test('every recorded hit kind serialises back to its server token', () { + final pipeline = resolved(pipelineHit()); + expect(pipeline, isA()); + expect((pipeline as SearchPipelineTarget).pipelineId, 7); + expect(pipeline.kind, SearchTargetKind.pipeline); + expect(pipeline.wire, pipelineHit()['target']); + + final version = resolved(versionHit()); + expect(version, isA()); + expect((version as SearchVersionTarget).pipelineId, 9); + expect(version.version, 2); + expect(version.wire, versionHit()['target']); + + final run = resolved(runHit()); + expect(run, isA()); + expect((run as SearchRunTarget).runId, 11); + expect(run.wire, runHit()['target']); + + final step = resolved(stepHit()); + expect(step, isA()); + expect((step as SearchStepTarget).runId, 11); + expect(step.sequence, 4); + expect(step.stage, 'builder'); + expect(step.visit, 2); + expect(step.wire, stepHit()['target']); + + final field = resolved(fieldHit()); + expect(field, isA()); + expect((field as SearchFieldTarget).runId, 11); + expect(field.sequence, 4); + expect(field.field, 'output'); + expect(field.wire, fieldHit()['target']); + + final artifact = resolved(artifactHit()); + expect(artifact, isA()); + expect((artifact as SearchArtifactTarget).url, '/artifacts/11/4/notes.md'); + expect(artifact.runId, 11); + expect(artifact.sequence, 4); + expect(artifact.wire, artifactHit()['target']); + }); + + test('a payload without its identity is reported as unresolvable', () { + expect(unresolved({}).reason, 'no recorded target payload'); + expect(unresolved(pipelineHit({'id': null})).reason, contains('pipeline')); + expect( + unresolved(versionHit({'pipeline_id': 9, 'version': 0})).reason, + contains('version'), + ); + expect(unresolved(runHit({'id': 0})).reason, contains('run')); + expect( + unresolved(stepHit({'run_id': 11, 'sequence': 0})).reason, + contains('step'), + ); + expect( + unresolved(fieldHit({'run_id': 11, 'sequence': 4, 'field': ' '})).reason, + contains('field'), + ); + expect(unresolved(artifactHit({'url': ' '})).reason, contains('artifact')); + expect( + unresolved({'kind': 'future_kind', 'target': 'widget:7'}).reason, + 'no recorded target payload', + ); + }); + + test('a hit without a matching recorded token is unresolvable', () { + expect( + unresolved({ + 'kind': 'run', + 'run': {'id': 11}, + }).reason, + 'recorded target is missing', + ); + expect( + unresolved({...pipelineHit(), 'target': 'pipeline:8'}).reason, + contains('does not match'), + ); + expect( + unresolved({...stepHit(), 'target': 'run:11:5'}).reason, + contains('does not match'), + ); + }); + + test('a serialised target parses back to the same identity', () { + final targets = [ + resolved(pipelineHit()), + resolved(versionHit()), + resolved(runHit()), + resolved(stepHit()), + resolved(fieldHit()), + resolved(artifactHit()), + ]; + for (final target in targets) { + final parsed = SearchTarget.fromWire(target.wire); + expect(parsed, target, reason: target.wire); + expect(parsed!.wire, target.wire, reason: target.wire); + } + + // The token names the visit's run and sequence, not its stage/visit facts. + final step = resolved(stepHit()) as SearchStepTarget; + final parsed = SearchTarget.fromWire(step.wire) as SearchStepTarget; + expect(parsed, step); + expect(parsed.stage, isNull); + expect(parsed.visit, isNull); + }); + + test('a token outside the server vocabulary names no target', () { + for (final token in const [ + '', + ' ', + 'widget:7', + 'pipeline:0', + 'pipeline:7:v0', + 'run:11:0', + 'run:11:4:', + 'http://example.test/not-an-artifact', + ]) { + expect(SearchTarget.fromWire(token), isNull, reason: token); + } + expect(SearchTarget.fromWire('run:11'), const SearchRunTarget(11)); + expect( + SearchTarget.fromWire('pipeline:7:v2'), + const SearchVersionTarget(7, 2), + ); + expect(SearchTarget.fromWire('pipeline:7'), const SearchPipelineTarget(7)); + }); +}