0.9.16: finish a switch that stopped part way, help topics, and screen-reader choices #192

Merged
ethan-hann merged 23 commits from integration-0916 into main 2026-10-26 22:36:41 -05:00
Owner

Closes #161 and #168.

#168: after SavePoint is killed mid-checkout, Switch again refused with unsaved changes. The finish now writes the target's copy of the files the stopped switch was changing (skipping those that already hold it, checked by size then blob hash), then moves the folder to the target. Any other change, an edited file the switch removes, or a folder the review could not check holds the finish back before anything is written and offers only Discard, with copy saying why. The launch dialog counts the files finishing will replace and names them for the saves folder. Case-only renames finish on Windows and macOS. D31.6 records it.

#161: How SavePoint works gains three topics (how the game starts, files to leave out, cloud saves), linked from the editor's question buttons; Back restores the editor's scroll position and focus. Every single-choice list is a ChoiceListBox: a named group of radio buttons with selection and toggle state for UIA, VoiceOver and Orca, arrow keys that move and wrap, and a lint test against plain ListBoxes used that way.

Both were implemented test-first and reviewed by a separate reviewer (#168 twice), and the branch was checked against the coding standards from PR 189 (fixes in 13bd91d; LaunchRig setup cost is #190, the list separator #191). The local Windows gate passed on this branch. Version 0.9.16.

Closes #161 and #168. #168: after SavePoint is killed mid-checkout, Switch again refused with unsaved changes. The finish now writes the target's copy of the files the stopped switch was changing (skipping those that already hold it, checked by size then blob hash), then moves the folder to the target. Any other change, an edited file the switch removes, or a folder the review could not check holds the finish back before anything is written and offers only Discard, with copy saying why. The launch dialog counts the files finishing will replace and names them for the saves folder. Case-only renames finish on Windows and macOS. D31.6 records it. #161: How SavePoint works gains three topics (how the game starts, files to leave out, cloud saves), linked from the editor's question buttons; Back restores the editor's scroll position and focus. Every single-choice list is a ChoiceListBox: a named group of radio buttons with selection and toggle state for UIA, VoiceOver and Orca, arrow keys that move and wrap, and a lint test against plain ListBoxes used that way. Both were implemented test-first and reviewed by a separate reviewer (#168 twice), and the branch was checked against the coding standards from PR 189 (fixes in 13bd91d; LaunchRig setup cost is #190, the list separator #191). The local Windows gate passed on this branch. Version 0.9.16.
A switch killed during the checkout leaves HEAD and the index at the old
snapshot with some files already rewritten. "Switch again" ran a plain
checkout, which read those files as local changes and refused with
DirtyWorkingTreeException, so the switch could never be finished (only a
discard got out).

Approach: when the folder holds a note for this same target, the switch
now (1) refuses a change anywhere outside the switch's own paths
(plan.Touched, plus the files the patterns name, which are never in the
way), as a normal switch does, and (2) before the usual checkout, runs
"git checkout <target> -- <paths>" over the changed or new files that the
switch writes (plan.Written), with the paths on stdin
(--pathspec-from-file, NUL separated, literal). A pathspec checkout
writes the target's copy and its index entry without looking at what the
file holds, which is what the stopped switch was doing. Nothing outside
those paths is forced, so the checkout that follows still moves HEAD and
still refuses anything else. The step runs after the index alignment, so
the files the patterns name and their skip-worktree marks are untouched
and behave as in a normal switch. It is a write git call, so the folder
pin and marker are rechecked right before it starts; it runs under
NoRepairWhileWriting, so no index repair follows; a failure leaves the
note. The switch check (CheckSwitchAsync) gets the same outside-change
refusal, so a launch preview agrees with the switch.

Observed reds, before the change (FinishSwitchTests):
- Switching_again_finishes_a_switch_that_was_killed_part_way_and_clears_the_note
  (branch and commit): DirtyWorkingTreeException "The install folder has
  changes that are not captured." from RunCheckoutAsync.
- A_killed_switch_that_stood_a_folder_where_a_file_was_is_finished_too,
  Finishing_leaves_the_files_the_games_patterns_name_as_the_player_has_them,
  A_new_file_the_games_patterns_name_does_not_stop_the_finish,
  The_same_switch_finishes_once_the_player_puts_an_outside_change_back: the
  same DirtyWorkingTreeException.
- The_switch_check_refuses_an_unsaved_change_outside_the_files_the_killed_switch_writes
  (edit and new): "Assert.Throws() Failure: No exception was thrown".

Passed on first run, checked by mutation (each fails when broken):
- the outside-change refusal (disabled the throw): the three
  An_unsaved_change_outside_... cases, the two check cases and
  The_same_switch_finishes_once_... fail with "No exception was thrown".
- A_forced_switch_still_finishes_... (dropped --force),
  Discarding_still_returns_... (dropped the note clear) and
  The_switch_check_passes_for_the_switch_that_was_killed_part_way (empty
  in-switch set) all fail.
- FolderRecheckTests.A_folder_swapped_for_a_link_before_the_files_of_a_stopped_switch_are_written_...
  (first version passed vacuously; with the decoy file made distinct it
  failed when the recheck was removed from the new step: a-only.txt was
  overwritten in the decoy).
The "How SavePoint works" page gains three topics: what Steam and GOG
Galaxy do with the saves SavePoint changes and removes (and when to turn
cloud saves off), the two lists of files to leave out with what * and **
mean, and Run the .exe versus Through Steam plus what "Knowing when
you've stopped playing" is for.

The editor's "How do these rules work?", "Does my store sync saves?" and
"When do I need this?" (program name) answers now end with a link that
opens the page at the matching topic. IShellContext.ShowHelp takes an
optional topic; an open page moves to it. The page scrolls the topic's
heading to the top and focuses it so a screen reader reads from there.

Observed reds (before the code):
- HowItWorksViewModelTests, 9 tests: Assert.Equal 13 topics, actual 10;
  Single() found no topic for each new section; Section expected
  FilesToLeaveOut/CloudSaves, actual null.
- HowItWorksShellTests: page.Section expected FilesToLeaveOut/CloudSaves,
  actual null.
- GameEditorGuidanceTests (rules, cloud, process): Assert.True(HasLink)
  was False.
- HowItWorksViewTests scroll and focus: with the view's section code
  switched off, Assert.Same(heading, Focused) failed (focus stayed on
  the Back button) for all four tests.
The launch choice ("How to start the game") and the other choices of one
among a few (theme, layout cards, accent swatches, the Sidebar/Library
switch, the History view switch, the Activity scope switch, and the cards
after playing) were plain lists to assistive technology. ChoiceListBox
is a ListBox whose automation peer is a named Group and whose options are
RadioButton peers that keep the selection pattern, so each option is
announced with its selected state.

Its arrow keys also move the choice: Down and Right go forward, Up and
Left go back, wrapping at the ends, flipped for right-to-left. The list's
own handling did nothing for options in a UniformGrid, so the launch
choice could not be changed with the arrow keys.

Observed reds (before the code):
- ChoiceListSemanticsTests.A_choice_of_one_is_a_named_group_of_radio_buttons,
  8 cases: Assert.Equal(Group, List) for each list.
- ChoiceListSemanticsTests launch choice with Down: expected selected
  index 1, actual 0 (focus and selection did not move).
- ChoiceListSemanticsTests.No_choice_of_one_in_the_app_is_left_as_a_plain_list:
  five views still declared a plain ListBox for a choice.
- Mutation checks: an option peer without the selection pattern makes the
  option-state tests fail (0 options found); Right mapped to no step makes
  the arrow-key tests fail for the launch choice, the layout cards and the
  theme selector.
Review of the finish found four must-fix problems and one should-fix.

M1. A stopped switch to the target being started never counted as dirty,
so a change the player made outside the switch's files had no callout,
no Discard, and the failure card's "Review the changes" looped. The
launch now reads StoppedSwitchReview (new GitEngine.ReviewStoppedSwitchAsync)
for a folder whose note names the target: unsaved changes in its way make
the folder Dirty, ChangesOutsideSwitchCount says how many, and no finish
target is offered. The dialog shows the unfinished-switch callout with
Discard and copy that says why finishing waits. A discard then lets the
same switch finish.

M2. On a drive that ignores case, a file the switch renames only in case
(with new content) was matched Ordinal against git's spelling, and the
old-spelling index entry blocked the normal checkout. Matching now uses
the system comparer, pathspecs keep the target's spelling, and the
old-spelling index entry is dropped (update-index --index-info) before
the checkout that moves HEAD.

M3. The finish could write files and then be refused by git for an edited
file the switch removes. That edit (a tracked file in plan.Gone that
exists and differs from HEAD) is now unsaved work refused up front, so
nothing is written.

M4. The preview and dialog say that finishing replaces the files the
switch was changing, including changes made since it stopped, with a
count of files that hold neither snapshot's copy; the saves folder names
up to five of them and counts the rest. A half-written file looks the
same as a player edit, so both are counted.

S1. The finish no longer rewrites a file that already holds the target's
bytes: size is compared first, only same-size files are hashed, a match
only gets its index entry set (git reset <target> -- paths) and keeps its
modification time. Files it does write are reported as progress in
batches, since git prints no meter for a pathspec checkout.

Observed reds (before each change):
- FinishSwitchCaseRenameTests (all three cases, "a's pack", "a's p", ""):
  DirtyWorkingTreeException "The install folder has changes that are not
  captured." from the checkout that follows the forced step.
- FinishSwitchTests.An_edited_file_the_switch_would_remove_refuses_before_anything_is_written:
  "Assert.Equal() Failure: Collections differ" (Data/mod.pak had been
  written before the refusal).
- FinishSwitchTests.The_switch_check_refuses_an_edited_file_the_switch_would_remove:
  "Assert.Throws() Failure: No exception was thrown".
- FinishSwitchTests.A_file_that_already_holds_the_targets_bytes_is_not_written_again and
  A_switch_killed_after_the_index_reached_the_target_but_before_head_moved_...:
  "Assert.Equal() Failure: Values differ" on shared.dat's modification
  time (2020-01-01 expected, now actual).
- FinishSwitchTests review tests (4): "Collections differ", actual empty.
- FinishSwitchTests.Finishing_reports_the_files_it_writes_though_git_prints_no_meter_for_them:
  "Assert.Contains() Failure: Filter not matched in collection".
- LaunchStoppedSwitchReviewTests: Dirty expected True actual False;
  ReplacedFileCount expected 1 or 7, actual 0 (5 of 7 failed).
- LaunchDialogViewModelTests (7): ReplacedNote empty, body still the
  "can't finish the switch" copy; LaunchUnfinishedSwitchFlowTests: body
  did not contain "2 files have changes that aren't saved".

Passed on first run, checked by mutation (each fails when broken):
- the same-size hash check (always Target) fails
  A_file_of_the_targets_size_with_other_bytes_is_written_again once it also
  asks the review for the file; always Other fails the two mtime tests.
- dropping the edited-removed-file check fails 3 FinishSwitchTests.
- dropping the old-spelling index removal fails all three case tests.
- Starting_is_refused_before_anything_is_written...: failed when both the
  launch's Dirty and the engine's refusal were disabled.
- LaunchDialogViewModelTests.A_folder_with_no_stopped_switch_gets_no_replacement_note:
  failed when the UnfinishedSwitch filter was removed.
- A file removed by the kill before its new copy was written is finished
  by git alone, so that test documents the case and has no mutation.
Each option of a ChoiceListBox is now also a toggle provider: On when
selected, Toggle() chooses it, and the toggle-state change is raised when
the selection changes. The macOS and Linux bridges read a radio button's
state only from it.

Coming Back from a help page opened by an editor explanation's link now
scrolls the form to where it was and puts focus on that explanation's
question instead of the name field. The help page looks its heading up at
background priority.

Copy: the cloud-saves topic says to turn cloud saves off before the next
start and that a save the store brings back joins the profile's next
snapshot, and names GOG Galaxy only where it runs; the start topic drops
its self-contradicting Linux clause; the files topic keeps the rule
mechanism apart from the logs rationale, which now belongs to the default
rules. The editor's cloud-saves notes also cover switching to a profile
with fewer saves. Comments on ChoiceListBox and the list theme corrected.

Observed reds (before the code):
- ChoiceListSemanticsTests option toggle, 8 cases: Assert.IsAssignableFrom
  IToggleProvider failed, actual ChoiceOptionPeer; Toggle() test the same.
- ChoiceListSemanticsTests lint sample with a plain ListBoxItem inside a
  ChoiceListBox: expected True, actual False. The self-closing sample
  then failed the first draft of the new rule (expected False, actual
  True) and the rule was tightened.
- GameEditorGuidanceViewTests Back: scroll offset expected 333, actual 0;
  cloud link Back: focused element was the Name TextBox, not the question.
- HowItWorksViewModelTests, 5 cases: missing "before you next start the
  game", "Running the .exe avoids that.", Linux copy still naming GOG and
  not saying Steam games on Linux need Steam, logs text still in the files
  body. GameEditorCloudSavesTests, 2 cases: copy lacked the fewer-saves
  clause.
- Mutation checks for tests that passed first run: group peer without the
  selection pattern fails the group test (8 cases); Continue tab
  navigation fails the Tab test (2); no IsEnabled check fails the
  disabled test; ignoring FlowDirection fails the right-to-left test.
  The name-field arrow test cannot be flipped by removing the
  e.Source guard, because the text box handles the key before it bubbles.
Final review round on the finish of a stopped switch.

Progress. The finish reported Observe(n, files) and then git's own meter
reported on the same reporter, so the bar could jump to the written count
and back. The reporter now keeps the files and bytes the finish wrote
(ObserveFinishing) and adds git's counts to them, and the byte estimate
spreads only the rest of the plan over git's count.

Reads. The scan is split: the blocking changes take no file read, and
comparing files with the snapshots (size first, then a hash of same-size
files) happens only for the preview's count and for the switch itself. A
start and CheckSwitchAsync no longer hash; ReviewStoppedSwitchAsync takes
listReplaced. BlobHasher checks its token between reads.

Preview. A review that fails is no longer stored as nothing (which offered
Finish again): the folder counts as blocked, StoppedSwitchUnchecked says
SavePoint could not check it, and Discard is the way out with copy that
says why.

Copy. The replaced-files note names the snapshot the switch was heading
to and puts the names inline in brackets. The changes-in-the-way copy no
longer says finishing would run over new files; it says SavePoint cannot
tell them from the switch's own files, so it will not finish until they
are gone, and that Discard removes new files too. "Stopped switch" is now
"the last switch".

Nits. Two comments that were wrong are fixed (a held file's index entry
moves and the verify pass finds it; batches can be half written, which is
safe because the note stays). The index is no longer restored twice on the
lock path.

Observed reds (before each change):
- ProgressReporterFinishingTests: "Values differ" (BytesDone 50, expected
  30; then FilesDone 6, expected 7, after git's count of 1 of 4).
- FinishSwitchTests.The_switch_check_reads_no_file_to_compare_it and
  A_review_that_does_not_list_the_replaced_files_reads_no_file_...:
  "Assert.Empty() Failure: Collection was not empty".
- LaunchStoppedSwitchReviewTests.Starting_that_is_refused_for_a_change_in_the_way_reads_no_file:
  "Collection was not empty"; Starting_the_switch_reads_each_file_...:
  "Assert.Single() Failure: The collection contained 2 matching items";
  A_preview_that_cannot_check_the_folder_...: Dirty expected True, actual
  False.
- LaunchDialogViewModelTests (7) and the flow test: the old copy.

Passed on first run, checked by mutation (each fails when broken):
- BlobHasher without its token check: the cancelled-token test fails.
- A batch size above the file count: the part-way batch failure test fails.
- A held file no longer tolerated in the batch step: the held-file test
  fails (Windows only; it is skipped and listed for the Linux gates).
Linux: a file with the target's bytes was never recognized on a drive that
keeps no permissions. The finish compared the file's executable bit with
the target's mode, but a Windows drive under WSL shows every file as
executable, and git is told to ignore the bit there (core.filemode false),
so a right file counted as a wrong one: it was neither kept nor counted,
and nothing was read. The finish now looks at the bit only when the
repository's core.filemode says git does (read from the config file, no
git process; RepoConfigFile.ReadValue). Windows has no bit.

Preview test: A_half_finished_switch_to_this_target_is_a_pending_switch_and_not_unsaved_work
wrote new content into a file the switch removes. A kill never does that
(git removes a file whole), and the content is the player's, which the new
design treats as unsaved work. The test now leaves the file gone, as a
kill does, and a new test says that edited content in it is unsaved work.

EmptyFolderTests.A_folder_below_a_link_added_after_the_snapshot_is_not_made_through_it:
where git lists the link as a new file (a symbolic link on Linux), it is a
change outside the switch's files, so the finish is refused before it
writes anything. The test accepts that refusal there and still checks
that nothing is made through the link; the junction on Windows runs the
finish as before.

IndexRepairTests.An_index_that_is_damaged_again_right_after_the_repair_...:
the hook damages the index while the other read of the pair may still
have it open, and Windows refuses the write. Nothing in the finish, the
review or the hashing opens the index or runs in this path, and the test
passed 11 runs alone, so this is a race in the test's hook; it now waits
for the file to be free. It was not reproduced, so there is no red.

Observed reds before the change:
- Linux (WSL), FinishSwitchTests: The_switch_reads_each_file_of_the_targets_size_once
  "Assert.NotEmpty() Failure: Collection was empty";
  A_file_that_already_holds_the_targets_bytes_is_not_written_again and
  A_switch_killed_after_the_index_reached_the_target_...: mtime
  "Expected: 2020-01-01T12:00:00Z Actual: 2026-10-26T13:10:18Z";
  A_file_of_the_targets_size_with_other_bytes_is_written_again:
  "Item not found in collection".
- Linux, LaunchStoppedSwitchReviewTests: "The collection did not contain
  any matching items" and "Assert.True() Failure".
- Linux, EmptyFolderTests.A_folder_below_a_link_...: DirtyWorkingTreeException.
- Windows and Linux, LaunchPreviewDirtyTests.A_half_finished_switch_...:
  "Assert.False() Failure, Actual: True".
Log why a stopped switch could not be checked, and tidy the 0.9.16 batch
Some checks failed
Docs / site (pull_request) Successful in 1m17s
Gate / linux (pull_request) Failing after 15m10s
Gate / windows (pull_request) Has been cancelled
13bd91df81
- A preview that cannot check a folder with a stopped switch now keeps the
  exception on the FolderReading and writes it to the diagnostic log as a
  warning. Red: A_preview_that_cannot_check_the_folder_logs_why_as_a_warning
  failed with "Assert.Single() Failure: The collection was empty".
- The replaced-files note builds no list punctuation in code: the named form
  is its own catalog message (launch.dialog.replacedNoteNamed) and the
  separator comes from common.listSeparator. Shown text is unchanged.
- Split the arrow-key choice test: selection for every row, and a new theory
  for focus staying on the option for every row but the layout switch. The
  new theory was mutation-checked (expecting the wrong option fails).
- BlobHasherCancellationTests uses Directory.CreateTempSubdirectory.
- Drop a duplicate expected-skip line already provided by linux-ci.txt.
- Explain why the editor form scroll offset lives on the view model.
- Restore the spacing after the colon on two unchanged launch.json keys.
On Linux, git refuses the checkout that ends a stopped switch when the
target's file already stands where HEAD has a folder: it takes the file
for an untracked one in the way of removing the folder's files. The
finish wrote the file with a path checkout first, so the refusal came
after the index already said the file was there, and the switch could
never be finished. Windows git answers this differently, which is why
only the Linux gate failed.

The finish now removes such a file (a stopped switch's own write) and
lets the checkout write it from the target, as a switch that never
stopped does. The removal is a guarded step ("remove-standing") like
the other deletions the engine makes itself.

Red, observed on Ubuntu 26.04 (ext4, git 2.53) before the change:
FinishSwitchTests.A_killed_switch_that_stood_a_folder_where_a_file_was_is_finished_too
and the new A_killed_switch_that_finished_the_file_where_a_folder_was_is_finished_too
both threw DirtyWorkingTreeException from RunCheckoutAsync. Both pass on
the VM after the change. The new folder-recheck test was mutation
checked by dropping the recheck call (red), then restored.
The test let go of the note from a background task after a fixed delay and
relied on the read's waits outlasting it, so a slow machine that ran the
task late had the read give up first. Read now takes an optional pause
callback in place of the sleep between tries; the test releases the file
there, so the first retry always finds it free.

Red: with the callback ignored (the old sleeping behavior) the test fails
on its assertion, the note comes back with no commits, the same result the
slow Windows run showed. Restored, all 13 UnreadableJournalTests pass.
Tests: the review names a file the player put where a folder was as
replaced and does not name the target's whole copy; a stopped switch to a
point that holds a folder where the old point had a file is finished; a
held file standing where a folder was is named and a repeat finishes; a
folder above a standing file turned into a link after the scan does not
send the removal outside. The half-written-file test is renamed to say
what it does.

RemoveStanding now refuses a file under a link or under another letter
case, as RemoveDisplaced does, and the finish puts the index back for any
SavepointException (it missed the unreadable-file and disk-space errors).
The FinishScan comment no longer calls standing files the switch's own
writes; some are the player's.

Red: the link test failed with no exception thrown (the removal went
through the link) before the check. Mutation checks: dropping the
replaced bookkeeping for standing files failed the new review test; skipping
the rewrite step failed the new folder-where-a-file-was test (and 12
older ones); both restored. FinishSwitchTests and FolderRecheckTests pass
on Windows and on the Linux VM. No test for the unreadable-file case: it
needs a file the process may not read.
List the new Windows-only standing-file test among the Linux skips
All checks were successful
Release / windows (push) Successful in 3m24s
Docs / site (pull_request) Successful in 1m26s
Gate / linux (pull_request) Successful in 17m53s
Release / checksums (push) Successful in 31s
Gate / windows (pull_request) Successful in 40m47s
Docs / site (push) Successful in 1m29s
Release / linux (push) Successful in 2m1s
61286c0945
Sign in to join this conversation.
No reviewers
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ethan-hann/SavePoint!192
No description provided.