Files
pipelines/app/notes/D1.md
T

17 KiB
Raw Blame History

D1 — run changes and the file diff viewer

New feature under lib/features/changes/; no server, legacy web/Android or pubspec changes remain after manager acceptance corrections.

Current manager acceptance (supersedes earlier presentation evidence below)

The pipeline's bundled font and fixed green/red palette were rejected against the user's native-defaults requirement. Manager removed both and the font assets without changing raw patch, capture or visit semantics. Typography inherits the host; colours use native semantic roles and no row tint. The original candidate and its review evidence remain referenced at15cca17; later font/palette evidence in this note is historical, NOT evidence for the final native-defaults patch.

Updated regressions failed against the original overrides, then all47 focused tests passed after correction; analyzer clean. Fresh fixture web build and changes_probe passed (including absence of custom font), producing18 new captures under approved temp/native-diff-manager-captures. Manager inspected both native phone2x rendered views. Preview/shell integration and mobile remain unverified.

Public API

Import the barrel:

import 'package:pipelines_app/features/changes/changes.dart';

Integration widgets:

  • ChangesViewer({Key? key, required List<JsonMap> steps})
    • The run detail's steps exactly as returned by get_run. Pass the same list instance until the server reply changes: captures and the summary are derived once per list identity, not on every rebuild or filter keystroke.
    • It fills the available height, so place it in a bounded parent (Scaffold body, tab body or Expanded). It does not open a socket or request data.
  • FileDiffViewer({Key? key, required FileChange file, VoidCallback? onClose})
    • The reusable viewer for one recorded file. Without onClose it pops the enclosing route.
  • Future<void> showFileDiffViewer(BuildContext context, FileChange file)
    • Opens the platform modal: showDialog with a Material Dialog on Android/desktop/web, showCupertinoDialog with CupertinoPopupSurface on iOS/macOS.

Data and pure helpers exported for integration/tests:

  • FileChange — path, kind, patch (server bytes or null), binary, truncated, beforeMode, afterMode, steps; FileChange.fromJson(JsonMap), FileChange.tryParse(dynamic).
  • ChangeCapture — status, scope, files, skipped, omitted, diagnostic; ChangeCapture.fromJson(JsonMap).
  • StageCapture / StageCapture.fromStep(JsonMap) / stageCaptures(steps) — one stage visit per step, ordered by numeric sequence, including steps with no capture. sequence is the run-wide step ordinal (ordering and keys); visit is the display visit number within the stage.
  • RunChanges / runChanges(steps) / runChangesFor(captures) — final-state aggregate (last recorded visit wins per path; each path counted once) with the same fields. runChangesFor avoids re-deriving captures a caller already has.
  • parseUnifiedPatch, PatchHunk, PatchLine, ChangeLineKind, gutterWidth, gutterText, changeStat, changeKind, changeKindLabel, changeKindTitle.
  • Wording: runChangesHeader, runChangesNote, changesListSummary, noChangeDetail, patchUnavailableReason, changeEntryTags, changeRowMeta, changeFileMeta, fileChangesSummary, filterFileChanges, changePositionLabel, binaryDiffMessage, truncatedPatchNote, noLineChangesMessage, missingCaptureDetail, unavailableCaptureDetail, malformedCaptureDetail, emptyCaptureDetail, partialCaptureDetail.

Example integration:

final steps = (detail['steps'] as List).cast<JsonMap>();
// ...
ChangesViewer(steps: steps)

The manager owns shell/run-detail registration; this item does not edit them.

Recorded-evidence semantics (matches web/src/changes.js)

  • file_changes == null is missing evidence, not “no changes”. A running/waiting step is “pending”; any other missing capture is counted and named. The UI says the capture is unavailable and explicitly says that does not mean the workspace was unchanged.
  • status: "unavailable" means the snapshots could not be compared. No change list is fabricated; the server diagnostic is shown. A non-null file_changes value that is not an object is also unreadable evidence, so it is treated as unavailable with malformedCaptureDetail; it never becomes an empty capture.
  • A present complete capture with files: [] is the only “no changes observed” state (“the captured snapshots were identical”).
  • status: "partial", any per-file truncated, or any omitted count makes the run partial; skipped, omitted, truncated-file count and the diagnostic are shown. scope is shown per stage capture.
  • Files are grouped by stage/visit. The visit label is the recorded control.visit when it is positive (a resumed run), otherwise the visit's 1-based position among the steps of its own stage, ordered by sequence and stable for ties. This mirrors the web client's displayVisit; the run-wide step sequence is only the ordering/key, never shown as a visit number.
  • Kinds are added, modified, deleted and the safe changed fallback. Binary, truncated and mode-only entries carry labels; a mode-only entry has no text diff and says so.
  • The run summary is final-state: a path recorded by several visits is one row, keeping first-seen order and the last visit's kind/patch/stat/flags/modes, with the stage names that touched it. Per-stage sections still show each visit's own capture.
  • Filtering matches changed filenames case-insensitively (substring) and keeps missing/unavailable evidence sections visible. The counter names paths, matching the summary's unit; the sections below still list one row per visit.
  • A changed-file row's semantics label names the action, path, kind and visible meta (+N -M, binary/truncated/mode), so the excluded icon and subtitle are still announced.

Diff rendering

  • Only patch content is custom-drawn: @@ hunk headers, old/new gutter numbers, the shared +/-/space language, context and \ No newline markers.
  • The recorded ---/+++ file headers stay in the Raw view, matching the web rendered view; rendered content is the stat line and the hunks. Long lines scroll horizontally; vertical content scrolls inside the dialog. The Raw view keeps each recorded line on one line and scrolls sideways, like the web's white-space: pre pane, so a wrapped continuation can never be mistaken for a new patch line.
  • Patch/path text inherits the native host typography without a font-family, size or weight override. Manager removed the candidate's bundled code font: a previous visual review requested it, but that contradicts the user's explicit native-defaults requirement, which also applies to diffs. The web default may be proportional; no monospace guarantee is claimed. Raw patch bytes are unchanged. No bundled font or pubspec change remains.
  • Rendered/Raw is a native Material SegmentedButton or Cupertino CupertinoSlidingSegmentedControl. Copy patch and Close are native Material buttons/icon button or Cupertino buttons with exact labels.
  • Copy patch writes the recorded patch string byte-for-byte (trailing newline and truncated final line included). Copy is disabled when no readable patch exists.
  • Binary uses the honest binary message; truncated-with-patch shows the note plus the retained text; truncated-without-patch and mode-only show the recorded reason, never an invented empty diff.
  • Add/remove markers and stats use native semantic colours (Material primary/ error; Cupertino systemGreen/destructiveRed), with no bespoke palette or added tint. +/- and recorded gutter numbers distinguish changes without colour. Rows share the hunk width, at least the dialog width.
  • A Cupertino list row lets its recorded path wrap instead of inheriting the tile's single ellipsized line, and the Cupertino dialog surface is inset from the window edge (16 on phones, 40 on wide windows) so its native rounded corners are visible.

Files

lib/features/changes/changes.dart
lib/features/changes/domain/change_capture.dart
lib/features/changes/domain/change_kind.dart
lib/features/changes/domain/change_wording.dart
lib/features/changes/domain/file_change.dart
lib/features/changes/domain/patch_models.dart
lib/features/changes/domain/run_changes.dart
lib/features/changes/domain/unified_patch.dart
lib/features/changes/widgets/change_style.dart
lib/features/changes/widgets/changes_viewer.dart
lib/features/changes/widgets/capture_section.dart
lib/features/changes/widgets/file_diff_viewer.dart
lib/features/changes/widgets/patch_view.dart
assets/fonts/RobotoMono.ttf
assets/fonts/OFL.txt
pubspec.yaml                        (fonts + assets declaration)
test/features/changes/fixtures.dart
test/features/changes/widget_hosts.dart
test/features/changes/unified_patch_test.dart
test/features/changes/run_changes_test.dart
test/features/changes/changes_viewer_test.dart
test/features/changes/diff_presentation_test.dart
tool/changes_probe_entry.dart
tool/changes_probe.mjs

Every path above is new except pubspec.yaml, which gains only the RobotoMono family and the font licence asset declaration.

Checks

Presentation revision (bundled code face, diff colours/tints, Cupertino rows and dialog inset) re-ran the full set:

  • /Users/alan/development/flutter/bin/flutter test — 76 tests passed.
  • /Users/alan/development/flutter/bin/flutter test test/features/changes — 47 tests passed.
  • /Users/alan/development/flutter/bin/flutter analyze — No issues found.
  • /Users/alan/development/flutter/bin/dart format --output=none --set-exit-if-changed lib/features/changes test/features/changes tool/changes_probe_entry.dart — 20 files, 0 changed.
  • /Users/alan/development/flutter/bin/flutter build web — built build/web successfully.
  • node --check tool/changes_probe.mjs — passed.
  • /Users/alan/development/flutter/bin/flutter build web --target tool/changes_probe_entry.dart --output build/probe-web-fix — built.
  • node tool/changes_probe.mjs --root build/probe-web-fix --out <public>/d1 — passed every check (11 checks, below).

flutter pub get resolved the existing lock; pubspec.lock is unchanged.

Real browser evidence

Fixture entry tool/changes_probe_entry.dart, driven by tool/changes_probe.mjs (loopback, OS-assigned port, headless Chrome, Flutter semantics enabled). The fixture uses server-shaped captures for partial, complete, missing, unavailable and empty states, plus binary, truncated, mode-only, deleted, added and multi-hunk patches. /?visits=1 is a compact second fixture that repeats stages and records one explicit control.visit. It is rendering data only; no server or operator run touched.

Captures (in the run's public artifacts d1/):

  • d1-changes-phone-list.png (390×844, dark)
  • d1-changes-phone-diff.png
  • d1-changes-phone-raw.png
  • d1-changes-phone-copied.png
  • d1-changes-phone-filtered.png
  • d1-changes-phone-visits.png (390×844, repeated-stage visit labels)
  • d1-changes-phone-light-list.png, d1-changes-phone-light-diff.png, d1-changes-phone-light-diff-2x.png, d1-changes-phone-light-raw.png (light theme, 2x where glyphs and tints are inspected)
  • d1-changes-desktop-diff.png (1280×800)
  • d1-changes-desktop-list.png
  • d1-changes-desktop-light-list.png, d1-changes-desktop-light-diff.png
  • d1-changes-cupertino-diff.png (1280×800, Cupertino fixture)
  • d1-changes-cupertino-light-list.png (390×844, wrapped paths), d1-changes-cupertino-light-diff.png, d1-changes-cupertino-light-diff-2x.png (390×844, inset popup)

Observed checks from d1-probe.json:

  • Root / served text/html; charset=utf-8.
  • assets/FontManifest.json lists a RobotoMono family and assets/fonts/RobotoMono.ttf is served as font/ttf (183,700 bytes), so the web build carries a real code face.
  • The body showed Changes probe and Capture unavailable, and a file row whose semantics label starts with Open diff for lib/features/changes/domain/unified_patch.dart (the label now also announces kind and meta).
  • Opening the diff changed document.body.innerText; Rendered, Raw patch, Copy patch and Close diff labels appeared.
  • Raw patch changed the body and produced a different PNG from the rendered capture; the raw semantics value contains the recorded ---/+++ header.
  • Clipboard readback after Copy patch started with --- "a/lib/features/changes/domain/unified_patch.dart" (540 bytes).
  • Filtering unified left both matching visit rows (unifiedRows: 2) and hid assets/pipelines-mark.png (binaryRows: 0); the counter read 1 of 6 changed paths match.
  • The visits fixture rendered implementer with Visit 1 and Visit 2, and reviewer with Visit 1 and the recorded control.visit Visit 6; the probe fails if either list differs.
  • Close diff returned to the list; the desktop and Cupertino viewers opened.

Measured from d1-changes-phone-light-diff-2x.png (Pillow): the light add tint is #E3F3E7 and the remove tint #FBE7E5 (ΔR 24); every changed line paints a 618 px (309 logical px) band — the full dialog content width — and the two added lines and one removed line are each 92/46 device px tall. Previously the tints were #FFD8E4/#F9DEDC (Δ 6,6,8) and only as wide as each line's text. Dark captures measure #394643 (green) and #4D3C42 (red) tints.

The screenshots show real Material and Cupertino controls, light and dark themes, phone and desktop widths, wrapped Cupertino paths and an inset Cupertino popup. Mobile targets were not built, installed or run.

Review revision

  • B1 (blocking, visit labels): StageCapture.visit is derived from positive control.visit else the stage position; sections render it instead of the run-wide sequence. Unit/widget tests cover repeated stages, a resumed visit and sequence ties; the browser visits fixture and capture above show the result.
  • A1 (malformed capture): a non-object file_changes is now unavailable with malformedCaptureDetail, never an empty “no changes” capture.
  • A2 (rendered headers): rendered view shows hunks only, matching the web rendered view; the exact headers remain in Raw and Copy.
  • A3 (re-derivation): ChangesViewer derives captures/aggregate on init and when the steps list changes, not on filter keystrokes; runChangesFor reuses those captures, and FileChange.withSteps reuses the parsed patch.
  • A4 (test fixtures): the run-changes test helpers now delegate to test/features/changes/fixtures.dart.
  • A5 (row semantics): the row label includes kind and visible meta.
  • A6 (filter counter): counts and names changed paths, matching the summary; the list remains per visit.
  • A7 (paging): unchanged; the one-file viewer API is the documented limit.

Presentation revision (UI review)

  • M1 (monospace): pubspec.yaml declares the bundled RobotoMono family (assets/fonts/RobotoMono.ttf, SIL OFL 1.1, licence in assets/fonts/OFL.txt) and monospaceText uses it on every platform. The browser build's FontManifest.json and font response are checked by the probe, and the 2x captures show even advances and aligned gutters.
  • M2 (add/remove colours and tints): the diff no longer uses Material tertiaryContainer/errorContainer. diffLineColors supplies theme-aware green/red pairs (light #116B33 on #E3F3E7, #B3261E on #FBE7E5; dark #7FE0A8/#FF9E9E on a 16% wash), the +N/-M stat is split into those two hues, and every line tint spans the full hunk width (at least the dialog width) via IntrinsicWidth inside a width-bounded scroll view.
  • M3 (Cupertino): list rows clear CupertinoListTile's inherited single-line cap so the recorded path wraps, and the Cupertino dialog is inset (16 on phones, 40 on wide windows) so its rounded corners are visible.
  • Nonblocking raw wrap: the Raw view now keeps one recorded line per line and scrolls horizontally (SelectionArea over a Text with softWrap: false), matching the web's pre pane.
  • Left as-is (nonblocking): list-row stat strings stay neutral (Android/web colour them), the unavailable diagnostic still appears in both the section meta and the note (web parity), and the one-file viewer has no paging.

Deliberate limits

  • One file per FileDiffViewer; the browser viewer's previous/next gallery paging is not implemented here. The task asked for a reusable one-file viewer.
  • The shell/run-detail screen is not wired; that remains the manager's integration step (feature lanes do not edit shell/main).
  • Run status gating (showRunChangesSummary, succeeded-only in the browser) is the caller's choice; ChangesViewer renders whatever steps it is given.
  • The bundled font is Latin/Greek/Cyrillic: a patch containing CJK or symbol glyphs outside that coverage falls back for those glyphs, so their advance may not be monospaced. Copy and Raw bytes are unaffected.
  • Android and iOS were not built, installed or run in this revision; the Cupertino path is verified only through the fixture's browser rendering and widget tests, so mobile remains unverified.
  • No backend capability is missing for this item: file_changes already carries status, scope, files, skipped, omitted, diagnostic, binary/truncated flags, modes and patches.