Files
pipelines/app/lib/features/changes/domain/change_wording.dart
T
alan d3a2369d1f Stage rows show cached share and cost; Changes explain no_patch_reason
Timeline stage rows add the cached share (when cache_known) and a positive
cost: 20.1M tokens · 97% cached · $1.42. The file viewer words each server
no_patch_reason, keeping the old truncated/binary text as the fallback.
2026-11-04 17:26:31 +00:00

210 lines
8.2 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;
}
/// The message for the server's `no_patch_reason`, or null when it sent none
/// or one this client does not know (the generic wording then applies).
String? noPatchReasonMessage(String? reason) => switch (reason) {
'binary' => 'Binary file; only its metadata was recorded.',
'file_size' => 'This file is over 1 MiB, so no diff text was recorded.',
'budget' =>
'The workspace snapshot ran out of text budget, so no diff text was '
'recorded.',
'lines' => 'The change is over 5,000 lines, so no diff text was recorded.',
'evidence_size' =>
"This visit's recorded changes reached their size limit, so this patch "
'was dropped.',
'git_status' =>
"This change was seen only in Git status, so the file's contents weren't "
'compared.',
'baseline' =>
"The file's content at stage start couldn't be recovered from Git, so no "
'diff was recorded.',
_ => null,
};
/// Why a file has no patch to render, in the entry's own recorded terms.
String patchUnavailableReason(FileChange file) {
final reason = noPatchReasonMessage(file.noPatchReason);
if (reason != null) return reason;
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 += ' ';
final count = capture.files.length;
text += '($count ${count == 1 ? 'file' : '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';