324 lines
17 KiB
Markdown
324 lines
17 KiB
Markdown
# 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:
|
||
|
||
```dart
|
||
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:
|
||
|
||
```dart
|
||
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.
|