Files
pipelines/app/lib/features/changes/domain/change_wording.dart
T
alan 9532ecddcf feat(app): page the run Changes surface one recorded visit at a time
The run-wide header, note, filter and matched-path counter still describe
every visit; below them Previous/Next move through the recorded visits in
run order without wrapping, and the shown visit keeps its own stage and
Visit N heading. A single recorded visit renders no pager.
2026-10-22 15:56:30 +01:00

186 lines
7.1 KiB
Dart

import 'change_capture.dart';
import 'file_change.dart';
import 'run_changes.dart';
import 'unified_patch.dart';
/// The honest messages the viewer and its tests share. Spelled once, matching
/// the web client's `web/src/changes.js`.
const binaryDiffMessage =
'This is a binary file: the server recorded the change but has no textual '
'diff to show.';
const truncatedPatchNote =
'The server truncated this patch at its capture limit; the raw text is the '
'whole record.';
const noLineChangesMessage = 'no line changes recorded';
/// A step with no capture recorded no evidence; it does not prove the workspace
/// was unchanged.
const missingCaptureDetail =
'This visit recorded no change capture (a historical step, or a stage that '
'does not capture). That does not mean the workspace was unchanged.';
const pendingCaptureDetail =
'The capture runs after the stage finishes; nothing is recorded yet.';
const unavailableCaptureDetail =
'The workspace snapshot could not be compared, so no changes can be shown.';
const emptyCaptureDetail =
'The captured snapshots were identical: the workspace was unchanged.';
const partialCaptureDetail = 'Partial capture: some changes may be missing.';
/// The Changes section header's one-line summary: the observed file count, the
/// total `+N -M`, and the honest capture caveats.
String runChangesHeader(RunChanges changes) {
if (changes.unavailable) return 'Changes · capture unavailable';
if (changes.files.isEmpty) {
if (changes.pending) return 'Changes · capture pending';
if (changes.partial) return 'Changes · partial capture';
if (changes.stepsWithChanges == 0) {
return 'Changes · not recorded for this run';
}
if (changes.missingCaptures > 0) return 'Changes · capture incomplete';
return 'Changes · no changes observed';
}
final stat = changeStat(changes.added, changes.removed);
final count = changes.files.length;
final label = stat.isEmpty
? '$count ${count == 1 ? 'file' : 'files'} changed'
: '$count ${count == 1 ? 'file' : 'files'} changed · $stat';
if (changes.partial) return '$label · partial capture';
if (changes.missingCaptures > 0) return '$label · capture incomplete';
return label;
}
/// The honest one-line note under the header for a capture that is not
/// complete, or "" when it was.
String runChangesNote(RunChanges changes) {
if (changes.unavailable) {
return changes.diagnostic.isNotEmpty
? changes.diagnostic
: 'The workspace snapshot could not be compared; the changes below may '
'be incomplete.';
}
var out = '';
if (changes.partial) {
out = partialCaptureDetail;
final caveats = <String>[];
if (changes.skipped > 0) caveats.add('${changes.skipped} files skipped');
if (changes.omitted > 0) caveats.add('${changes.omitted} omitted');
final truncated = changes.files.where((file) => file.truncated).length;
if (truncated > 0) caveats.add('$truncated truncated');
if (caveats.isNotEmpty) out += ' (${caveats.join(', ')})';
if (changes.diagnostic.isNotEmpty) out += ' ${changes.diagnostic}';
}
if (changes.missingCaptures > 0) {
if (out.isNotEmpty) out += ' ';
out +=
'Missing capture: ${changes.missingCaptures} '
'${changes.missingCaptures == 1 ? 'stage did' : 'stages did'} not '
'record changes.';
}
return out.trim();
}
/// The file list's own summary line.
String changesListSummary(RunChanges changes) {
final count =
'${changes.files.length} '
'${changes.files.length == 1 ? 'file' : 'files'} changed';
final stat = changeStat(changes.added, changes.removed);
return stat.isEmpty ? count : '$count · $stat';
}
/// Why no change is listed: a pending capture, an unavailable one, a missing
/// capture or a recorded none.
String noChangeDetail(RunChanges changes) {
if (changes.pending) return pendingCaptureDetail;
if (changes.unavailable) return unavailableCaptureDetail;
if (changes.stepsWithChanges == 0) {
return 'This run recorded no change capture (a historical step, or a stage '
'that does not capture).';
}
return emptyCaptureDetail;
}
/// Why a file has no patch to render, in the entry's own recorded terms.
String patchUnavailableReason(FileChange file) {
if (file.truncated) {
return "The server truncated this file's patch at its capture limit; no "
'diff text was recorded.';
}
if (file.otherModeChange) {
return "Only the file's mode changed (${file.beforeMode ?? ''}→"
'${file.afterMode ?? ''}); the server recorded no text diff.';
}
return 'The server recorded this change without a patch.';
}
/// The tags shown beside a file row: traits that change how the entry must be
/// read, never a fabricated diff.
List<String> changeEntryTags(FileChange file) => file.tags;
/// The row's secondary line for an aggregated entry: which stage(s) changed it
/// and how to read it.
String changeRowMeta(FileChange file) {
var out = file.steps.isEmpty ? '' : 'changed by ${file.steps.join(' → ')}';
for (final tag in changeEntryTags(file)) {
out += '${out.isEmpty ? '' : ' · '}$tag';
}
if (file.modeChanged && !file.binary) {
out +=
'${out.isEmpty ? '' : ' · '}mode ${file.beforeMode ?? ''}→'
'${file.afterMode ?? ''}';
}
return out;
}
/// A compact per-entry line for a file row: stat, tags and mode, or the honest
/// no-line-change note. Content-driven; no fixed cell widths.
String changeFileMeta(FileChange file) {
final parts = <String>[];
final stat = changeStat(file.added, file.removed);
if (stat.isNotEmpty) parts.add(stat);
parts.addAll(file.tags);
if (file.modeChanged && !file.binary) {
parts.add('mode ${file.beforeMode ?? ''}→${file.afterMode ?? ''}');
}
return parts.isEmpty ? noLineChangesMessage : parts.join(' · ');
}
/// A compact capture summary, e.g.
/// `partial (2 files), 1 skipped, 3 omitted · Excluded protected files.`.
/// Blank parts are omitted; an entirely blank capture renders as "".
String fileChangesSummary(ChangeCapture capture) {
var text = capture.status;
if (capture.files.isNotEmpty) {
if (text.isNotEmpty) text += ' ';
text += '(${capture.files.length} files)';
}
if (capture.skipped > 0) {
if (text.isNotEmpty) text += ', ';
text += '${capture.skipped} skipped';
}
if (capture.omitted > 0) {
if (text.isNotEmpty) text += ', ';
text += '${capture.omitted} omitted';
}
if (capture.diagnostic.isNotEmpty) {
if (text.isNotEmpty) text += ' · ';
text += capture.diagnostic;
}
return text;
}
/// Filters changed filenames by a case-insensitive substring, preserving the
/// recorded order. A blank query keeps every file.
List<FileChange> filterFileChanges(Iterable<FileChange> files, String query) {
final needle = query.trim().toLowerCase();
final all = files.toList(growable: false);
if (needle.isEmpty) return all;
return all
.where((file) => file.path.toLowerCase().contains(needle))
.toList(growable: false);
}
/// The `N of M` position label a viewer can show for its open file or for the
/// Changes visit on screen.
String changePositionLabel(int index, int count) => '${index + 1} of $count';