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