Files
pipelines/app/notes/D1.md
T

324 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.