vimamsa 0.1.26 → 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/appimage.yml +93 -0
  3. data/.gitignore +4 -1
  4. data/Dockerfile +7 -4
  5. data/README.md +62 -16
  6. data/custom_example.rb +43 -13
  7. data/doc/TODO.md +461 -0
  8. data/doc/bundling_plan.md +569 -0
  9. data/doc/key_bindings_report_plan.md +168 -0
  10. data/doc/missing_vim_bindings.md +71 -0
  11. data/doc/modules_settings_plan.md +433 -0
  12. data/doc/refactor_dedup_plan.md +117 -0
  13. data/doc/unused_code_plan.md +120 -0
  14. data/doc/vim_compatibility_plan.md +296 -0
  15. data/doc/vimlike_vim_conflicts.md +254 -0
  16. data/doc/vm_snapshots_plan.md +146 -0
  17. data/exe/run_tests.rb +117 -3
  18. data/exe/vimamsa +24 -4
  19. data/fonts/OFL-Oxanium.txt +93 -0
  20. data/fonts/Oxanium[wght].ttf +0 -0
  21. data/icon.png +0 -0
  22. data/img/demo.gif +0 -0
  23. data/lang/hyperplaintext.lang +6 -0
  24. data/lib/vimamsa/ack.rb +11 -1
  25. data/lib/vimamsa/actions.rb +4 -1
  26. data/lib/vimamsa/appimage_env.rb +35 -0
  27. data/lib/vimamsa/audio.rb +2 -5
  28. data/lib/vimamsa/bookmarks.rb +302 -0
  29. data/lib/vimamsa/buffer.rb +593 -82
  30. data/lib/vimamsa/buffer_changetext.rb +102 -42
  31. data/lib/vimamsa/buffer_cursor.rb +7 -0
  32. data/lib/vimamsa/buffer_list.rb +4 -0
  33. data/lib/vimamsa/buffer_manager.rb +4 -1
  34. data/lib/vimamsa/bundled_fonts.rb +32 -0
  35. data/lib/vimamsa/clipboard.rb +3 -0
  36. data/lib/vimamsa/conf.rb +59 -3
  37. data/lib/vimamsa/constants.rb +3 -0
  38. data/lib/vimamsa/crash_handler.rb +149 -0
  39. data/lib/vimamsa/debug.rb +4 -1
  40. data/lib/vimamsa/desktop_install.rb +96 -0
  41. data/lib/vimamsa/diff_buffer.rb +39 -10
  42. data/lib/vimamsa/easy_jump.rb +3 -0
  43. data/lib/vimamsa/editor.rb +263 -57
  44. data/lib/vimamsa/encrypt.rb +78 -29
  45. data/lib/vimamsa/file_finder.rb +4 -19
  46. data/lib/vimamsa/file_history.rb +3 -0
  47. data/lib/vimamsa/file_manager.rb +30 -15
  48. data/lib/vimamsa/fold.rb +226 -0
  49. data/lib/vimamsa/gui.rb +520 -106
  50. data/lib/vimamsa/gui_command_line.rb +208 -0
  51. data/lib/vimamsa/gui_dialog.rb +94 -42
  52. data/lib/vimamsa/gui_file_panel.rb +356 -25
  53. data/lib/vimamsa/gui_form_generator.rb +59 -35
  54. data/lib/vimamsa/gui_func_panel.rb +67 -22
  55. data/lib/vimamsa/gui_image.rb +3 -0
  56. data/lib/vimamsa/gui_keylog_panel.rb +246 -0
  57. data/lib/vimamsa/gui_menu.rb +23 -11
  58. data/lib/vimamsa/gui_select_window.rb +19 -48
  59. data/lib/vimamsa/gui_settings.rb +78 -37
  60. data/lib/vimamsa/gui_sourceview.rb +273 -19
  61. data/lib/vimamsa/gui_sourceview_autocomplete.rb +319 -90
  62. data/lib/vimamsa/gui_text.rb +63 -2
  63. data/lib/vimamsa/gui_theme.rb +606 -0
  64. data/lib/vimamsa/hook.rb +3 -0
  65. data/lib/vimamsa/hyper_plain_text.rb +3 -0
  66. data/lib/vimamsa/key_actions.rb +112 -13
  67. data/lib/vimamsa/key_binding_tree.rb +242 -215
  68. data/lib/vimamsa/key_bindings_notepad.rb +43 -0
  69. data/lib/vimamsa/key_bindings_report.rb +261 -0
  70. data/lib/vimamsa/key_bindings_vim.rb +354 -0
  71. data/lib/vimamsa/key_bindings_vimlike.rb +65 -9
  72. data/lib/vimamsa/langservp.rb +271 -54
  73. data/lib/vimamsa/macro.rb +3 -0
  74. data/lib/vimamsa/main.rb +14 -8
  75. data/lib/vimamsa/rbvma.rb +26 -1
  76. data/lib/vimamsa/search.rb +3 -0
  77. data/lib/vimamsa/search_replace.rb +11 -10
  78. data/lib/vimamsa/string_util.rb +120 -40
  79. data/lib/vimamsa/terminal.rb +3 -0
  80. data/lib/vimamsa/test_framework.rb +28 -2
  81. data/lib/vimamsa/tests.rb +3 -0
  82. data/lib/vimamsa/text_objects.rb +353 -0
  83. data/lib/vimamsa/text_transforms.rb +14 -0
  84. data/lib/vimamsa/util.rb +46 -7
  85. data/lib/vimamsa/version.rb +1 -1
  86. data/lib/vimamsa.rb +0 -1
  87. data/modules/color_highlight/color_highlight.rb +118 -0
  88. data/modules/color_highlight/color_highlight_info.rb +3 -0
  89. data/modules/dictation/dictation.rb +1054 -0
  90. data/modules/dictation/dictation_info.rb +3 -0
  91. data/modules/dictation/whisper_worker.py +273 -0
  92. data/modules/ollama/ollama.rb +107 -0
  93. data/modules/ollama/ollama_info.rb +3 -0
  94. data/modules/tts/tts.rb +119 -0
  95. data/modules/tts/tts_info.rb +3 -0
  96. data/run_e2e_vm.sh +28 -0
  97. data/run_tests_vm.sh +130 -0
  98. data/scripts/appimage/AppRun +54 -0
  99. data/scripts/appimage/Dockerfile +18 -0
  100. data/scripts/appimage/build.sh +19 -0
  101. data/scripts/appimage/build_in_container.sh +192 -0
  102. data/scripts/appimage/smoke_test.sh +27 -0
  103. data/scripts/demo/demo_steps.txt +59 -0
  104. data/scripts/demo/record_demo.rb +177 -0
  105. data/scripts/demo/shapes.rb +28 -0
  106. data/styles/134272-molokai.xml +3 -0
  107. data/styles/molokai_cyber.xml +48 -0
  108. data/styles/molokai_edit.xml +1 -0
  109. data/tests/support/virtual_keyboard.rb +254 -0
  110. data/tests/support/virtual_mic.rb +67 -0
  111. data/tests/test_ack.rb +22 -0
  112. data/tests/test_auto_format.rb +122 -0
  113. data/tests/test_autocomplete.rb +211 -0
  114. data/tests/test_autosave.rb +145 -0
  115. data/tests/test_basic_editing.rb +33 -3
  116. data/tests/test_bookmarks.rb +206 -0
  117. data/tests/test_bracket_match.rb +85 -0
  118. data/tests/test_bundling.rb +92 -0
  119. data/tests/test_color_highlight.rb +92 -0
  120. data/tests/test_command_line.rb +79 -0
  121. data/tests/test_command_line_file.rb +27 -0
  122. data/tests/test_context_menu_file.rb +129 -0
  123. data/tests/test_copy_paste.rb +80 -0
  124. data/tests/test_crash_handler.rb +39 -0
  125. data/tests/test_custom_two_phase.rb +92 -0
  126. data/tests/test_dialog_callback_errors.rb +44 -0
  127. data/tests/test_dictation.rb +294 -0
  128. data/tests/test_diff_buffer_name.rb +51 -0
  129. data/tests/test_double_click.rb +41 -0
  130. data/tests/test_drag_selection.rb +125 -0
  131. data/tests/test_e2e_cmdline.rb +116 -0
  132. data/tests/test_e2e_dictation.rb +98 -0
  133. data/tests/test_e2e_replace_char.rb +58 -0
  134. data/tests/test_extract_file_links.rb +55 -0
  135. data/tests/test_file_format.rb +217 -0
  136. data/tests/test_file_manager.rb +72 -0
  137. data/tests/test_file_panel.rb +269 -0
  138. data/tests/test_flash.rb +78 -0
  139. data/tests/test_fold.rb +111 -0
  140. data/tests/test_font_refresh.rb +56 -0
  141. data/tests/test_func_panel.rb +68 -0
  142. data/tests/test_grep_apply.rb +46 -0
  143. data/tests/test_gtk_sync.rb +126 -0
  144. data/tests/test_hpt_highlight_visible.rb +75 -0
  145. data/tests/test_hpt_link_highlight.rb +82 -0
  146. data/tests/test_jump_to_file.rb +41 -0
  147. data/tests/test_key_bindings.rb +208 -0
  148. data/tests/test_keylog_panel.rb +101 -0
  149. data/tests/test_lsp_clangd.rb +281 -0
  150. data/tests/test_lsp_jump.rb +87 -0
  151. data/tests/test_lsp_position_encoding.rb +49 -0
  152. data/tests/test_lsp_symbols.rb +68 -0
  153. data/tests/test_macro.rb +137 -0
  154. data/tests/test_markdown_highlight.rb +57 -0
  155. data/tests/test_mode_badge.rb +41 -0
  156. data/tests/test_notepad_bindings.rb +67 -0
  157. data/tests/test_popup_queue.rb +51 -0
  158. data/tests/test_random_edit.rb +109 -0
  159. data/tests/test_revert.rb +127 -0
  160. data/tests/test_startup_file.rb +58 -0
  161. data/tests/test_status_area.rb +50 -0
  162. data/tests/test_text_objects.rb +163 -0
  163. data/tests/test_text_transforms.rb +329 -0
  164. data/tests/test_tts.rb +68 -0
  165. data/tests/test_vim_bindings.rb +252 -0
  166. data/tests/test_vim_conflicts.rb +63 -0
  167. data/tests/test_window_layout.rb +219 -0
  168. data/vimamsa.gemspec +3 -1
  169. data/vm_guest_run.sh +109 -0
  170. metadata +112 -10
@@ -0,0 +1,117 @@
1
+ # Deduplication refactor: reduce source size by removing repeated code
2
+
3
+ ## Context
4
+
5
+ Goal: find repeated source code that can be refactored to shrink the codebase.
6
+ Findings come from a mechanical duplicate-block scan plus a file-by-file sweep of the
7
+ GUI and core layers; every item below was verified by reading both copies. Total
8
+ realistic reduction: **~250–300 lines** (of ~15k in lib/). Ordered in tiers from
9
+ zero-risk deletions to the larger structural extraction, so it can be cut short at any
10
+ tier boundary. Each tier is committed separately and verified with the test suite
11
+ (`ruby exe/run_tests.rb --headless`), plus the binding-scheme tests for Tier 5.
12
+
13
+ ## Tier 1 — dead / duplicate code, pure deletion (~80 lines)
14
+
15
+ 1. **Duplicate `Clipboard` class** — `editor.rb:483-505` re-defines `Clipboard#set/#get`
16
+ identically to `clipboard.rb` (the live, fuller copy with `[]`/`<<`, required at
17
+ rbvma.rb:37). Delete the editor.rb copy.
18
+ 2. **Dead body of `KeyBindingTree#to_s`** — `key_binding_tree.rb:416-458`: line 417 is
19
+ `return self.class.to_s`, making the remaining ~40 lines unreachable — and they are
20
+ a verbatim copy of the traversal in the method above (`394-413`). Delete the dead
21
+ body, keep the one-line return.
22
+ 3. **Unreachable fuzzy-filter tail** — `file_finder.rb:167-179`: verbatim copy of
23
+ `FileHistory.fuzzy_filter` (`file_history.rb:63-77`) sitting after an unconditional
24
+ `return` inside `filter_files`. Delete.
25
+ 4. **Dead wrapper `open_existing_file`** — `editor.rb:677-679` is a pass-through to
26
+ `open_new_file`. Delete and update callers (`grep -rn open_existing_file lib tests`;
27
+ includes `gui_command_line.rb`).
28
+
29
+ ## Tier 2 — route through helpers that already exist (~15 lines)
30
+
31
+ 5. **`get_repeat_num` not reused** — `buffer_changetext.rb:343-348` (`delete_line`) and
32
+ `buffer.rb:1473-1478` (`copy_line`) inline the exact body of the existing
33
+ `get_repeat_num` (`buffer.rb:757`). Replace both blocks with the call.
34
+ 6. **Margins set line-by-line** — `gui_form_generator.rb:34-37, 45-48` expand 4-line
35
+ margin blocks although `Gtk::Box#margin=` / `Gtk::Frame#margin=` monkeypatches exist
36
+ (`gui_dialog.rb:14-32`). Replace with `frame.margin = 8` etc.
37
+
38
+ ## Tier 3 — small single-file helper extractions (~50 lines)
39
+
40
+ 7. **Visual-selection transform envelope** — `buffer.rb`: `transform_selection` (1403),
41
+ `convert_selected_text` (1428), `style_transform` (1439), `set_line_style` (1453)
42
+ all repeat `return if !@visual_mode; r = get_visual_mode_range; txt = self[r]; …;
43
+ replace_range(r, txt); end_visual_mode`. Extract
44
+ `transform_visual_selection { |txt| ... }`; also share the style-marker wrapping
45
+ (`⦁`/`❙`/clear-gsub) used by the last two.
46
+ 8. **Indent/unindent shared range math** — `buffer.rb:330-362`: both methods repeat the
47
+ 6-line visual-line-range setup + `replace_range` + selection restore. Extract
48
+ `transform_selected_lines { |line| ... }`; each method becomes ~3 lines.
49
+ 9. **LSP documentSymbol request scaffolding** — `langservp.rb`: `document_functions`
50
+ (336) and `document_functions_grouped` (360) share ~12 lines of
51
+ ensure_open/params/write/wait/validate. Extract private
52
+ `request_document_symbols(fpath)` returning the symbols array or nil.
53
+ 10. **Git-root lookup** — `diff_buffer.rb:153` and `:182` duplicate the
54
+ `dir = …; git_root = \`git -C … rev-parse --show-toplevel\`` block. Extract
55
+ `buffer_git_root` helper.
56
+
57
+ ## Tier 4 — GUI cross-file widget helpers (~90 lines)
58
+
59
+ Helpers live next to the existing ones in `gui_dialog.rb` (`set_margin_all`,
60
+ margin monkeypatches) as module-level Vimamsa functions.
61
+
62
+ 11. **TreeView + ScrolledWindow scaffolding** — `gui_file_panel.rb:8-48`,
63
+ `gui_func_panel.rb:12-40`, `gui_settings.rb:194-210` build the same
64
+ TreeStore/TreeView (headers off, single-click, one ellipsized expanding text
65
+ column) inside a `ScrolledWindow(:never,:automatic)`, plus structurally identical
66
+ `row-activated` handlers. Extract e.g.
67
+ `build_list_tree(store, ellipsize:, text_col:) { |iter| … }` returning
68
+ `[tree, scrolled_window]`. (~30–40 lines)
69
+ 12. **Modal popup boilerplate** — `gui_dialog.rb:43-48`, `gui_form_generator.rb:17-31`,
70
+ `gui_settings.rb:90-93`, `gui_select_window.rb:46-52` all do
71
+ `Gtk::Window.new; set_transient_for($vmag.window); modal = true; title = …`, and
72
+ three have identical `run` (show-or-destroy). Extract `make_modal_window(title)`
73
+ factory + share `run`. (~20–25 lines)
74
+ 13. **Return/Escape CAPTURE key controller** — `gui_dialog.rb:90-108`,
75
+ `gui_form_generator.rb:84-97`, `gui_settings.rb:151-161`,
76
+ `gui_select_window.rb:104-148` wire the same EventControllerKey with
77
+ Return→submit / Escape→destroy. Extract
78
+ `on_submit_escape(widget, submit:, escape:) { |keyval| … }` with an optional block
79
+ for extra keys (select_window's Up/Down/Delete). (~20 lines)
80
+ 14. **Panel show/hide/toggle in gui.rb** — `gui.rb:1148-1245`: file/func panel pairs
81
+ build the same Paned wrapper and near-identical hide logic; toggle/refresh/init
82
+ trios differ only in the ivar. Extract `make_side_pane(widget, pos)` and collapse
83
+ the trios data-driven. (~15–20 lines)
84
+
85
+ ## Tier 5 — shared key-binding definitions (~80–110 lines, most careful)
86
+
87
+ 15. **`key_bindings_vim.rb` ⇄ `key_bindings_vimlike.rb`** share byte-identical blocks:
88
+ mode/minor-mode setup + cursor colors (vimlike:3-24 / vim:17-35), the
89
+ `_insert_move`/`insert_select_move`/`insert_move` helper methods (19 lines each),
90
+ insert-mode arrow/selection bindings, `f`/`F` char-find + count + BOL/EOL entries,
91
+ marks, READCHAR + macro-record entries, the entire Browse-mode block
92
+ (vimlike:310-324 / vim:323-337), and the audio minor-mode bindkeys.
93
+ Extract into a new `lib/vimamsa/key_bindings_common.rb` (add to rbvma.rb per
94
+ convention — or `require`d by both scheme files directly, like
95
+ key_bindings_notepad.rb already requires vimlike). Both scheme files keep only
96
+ scheme-specific content. Binding semantics must stay identical: later
97
+ `bindkey`/`add_keys` override earlier ones, so common content loads first in each
98
+ scheme file.
99
+
100
+ ## Verification
101
+
102
+ - After each tier: `ruby exe/run_tests.rb --headless` (full suite, ~150 tests).
103
+ - Tier 1 item 4: re-run `test_command_line` + `test_jump_to_file`.
104
+ - Tier 4: `test_func_panel`, `test_keylog_panel`, `test_file_manager`, plus a manual
105
+ smoke test of one dialog (search) and the select window (file finder) in a real run.
106
+ - Tier 5: additionally `ruby exe/run_tests.rb tests/test_vim_bindings.rb` and
107
+ `tests/test_notepad_bindings.rb` (excluded from the default suite; the vim one
108
+ replays sequences against a real-vim oracle) and `tests/test_key_bindings.rb`.
109
+ - Final: line-count before/after (`wc -l lib/vimamsa/*.rb`), E2E cmdline test focused,
110
+ one commit per tier.
111
+
112
+ ## Explicitly not doing (checked, already fine or not worth it)
113
+
114
+ - Marshal save/load, file-read/run-cmd error handling, forward/backward cursor
115
+ methods: already centralized (`editor.rb:320`, `util.rb:283/108`, direction params).
116
+ - CSS-provider one-liners and `GLib::Idle.add { message(…) }` wrappers: savings too
117
+ small relative to churn.
@@ -0,0 +1,120 @@
1
+ # Unused-code removal plan: further source size reduction
2
+
3
+ ## Context
4
+
5
+ Follow-up to refactor_dedup_plan.md (tiers 1–4 done, tier 5 skipped). Fresh scan
6
+ (July 2026) for methods whose names appear nowhere outside their own definition —
7
+ searched across lib/, exe/, tests/, modules/, custom_example.rb, and a real-world
8
+ user config (custom.rb + settings.rb), counting references in eval'd key-binding
9
+ strings and symbols but ignoring comment-only lines. Older local scan
10
+ reports (not in the repo) are stale — everything in
11
+ them was either already deleted or is now used; this file supersedes them.
12
+
13
+ Caveat that applies to everything below: any function is technically reachable
14
+ from the `:` command line (it evals Ruby) and from ~/.vimamsa/custom.rb on other
15
+ machines. "Unused" here means: no reference anywhere in the shipped code or this
16
+ machine's user config.
17
+
18
+ Realistic total: **~530 lines** (tiers A–C), plus an optional ~390-line
19
+ commented-out-code sweep (tier D). Verify each tier with
20
+ `ruby exe/run_tests.rb --headless`.
21
+
22
+ ## Tier A — dead methods, pure deletion (~350 lines)
23
+
24
+ Verified individually; body sizes in parens. Delete, including any
25
+ now-orphaned ivars/config noted inline.
26
+
27
+ **buffer.rb** (~87): `get_short_path` (7), `recalc_line_ends` (13),
28
+ `sanity_check_line_ends` (12) — near-duplicates of each other, both dead;
29
+ `context_menu_items` (34); `need_redraw!`/`need_redraw?`/`set_redrawed` (9) —
30
+ also remove the now-write-only `@need_redraw` assignment at buffer.rb:458;
31
+ `delete_active_selection` (7, marked "TODO: remove this function");
32
+ `save_as_check_callback` (5, references a commented-out `@unconfirmed_path`
33
+ mechanism; `save_as_callback` itself stays — it's live via editor.rb:474).
34
+
35
+ **buffer_changetext.rb** (~10): `paste_start_xclip` (10) — superseded GTK-clipboard
36
+ fallback; its only call site is already commented out (line ~115). Remove that
37
+ comment too and the `xclip` mention.
38
+
39
+ **debug.rb** (~48): `run_test` (16), `run_random_jump_test__tmpl` (32) — legacy
40
+ test infra referencing tests/test_<id>_output.txt files that no longer exist.
41
+ (`gui_sleep` stays — used elsewhere.)
42
+
43
+ **editor.rb** (~25): `paste_register` (4), `plug` (3),
44
+ `can_open_extension?` (7) — also delete the orphaned
45
+ `cnf.extensions_to_open = [...]` default in conf.rb:129; `filter_buffer` (11).
46
+
47
+ **file_finder.rb**: `updating?` (3).
48
+
49
+ **gui.rb** (~49): `start_profiler` (4) + `end_profiler` (5) — dev tools, keep if
50
+ used interactively; `gui_set_cursor_pos` (3), `handle_image_resize` (15,
51
+ "TODO:gtk4", connects a GTK3-only signal), `editor_area` (3),
52
+ `remove_extra_controllers` (15), `is_buffer_open` (4).
53
+
54
+ **gui_sourceview.rb** (~24): `show_controllers` (7), `cur_pos_xy` (3),
55
+ `sanity_check` (14).
56
+
57
+ **hyper_plain_text.rb**: `hpt_scan_audio` (26).
58
+
59
+ **key_binding_tree.rb**: `clear_modifiers` (3, body already commented out),
60
+ `cur_mode_str` (3).
61
+
62
+ **langservp.rb** (~15): `add_workspaces` (11, TODO stub),
63
+ `handle_responses` (4, empty TODO stub).
64
+
65
+ **macro.rb**: `dump_last_macro` (5).
66
+
67
+ **tests.rb**: `run_tests_0` (15) — broken (evals `test_write_0`, which doesn't
68
+ exist) and unused. Subsumed by Tier B if that is taken.
69
+
70
+ **util.rb** (~34): `running_wayland?` (11), `pipe_to_external` (17),
71
+ `expand_if_existing` (6).
72
+
73
+ ## Tier B — delete legacy tests.rb entirely (~190 further lines)
74
+
75
+ `lib/vimamsa/tests.rb` (201 lines) predates the tests/ + test_framework.rb
76
+ suite: `run_tests`/`run_edit_tests`/`EditorTests`, two hash-oracle macro tests
77
+ (`test_paste_0` is a hard `return` stub), and the LOREM_IPSUM/JABBERWOCKY
78
+ constants (referenced nowhere else). Only entry point is the `:run_tests`
79
+ action (key_actions.rb:259) bound to `C , t r` (key_bindings_vimlike.rb:376).
80
+ Delete the file, the require in rbvma.rb:73, the action entry, and the binding.
81
+ If an in-editor test runner is still wanted on that key, repoint it at the
82
+ modern suite instead.
83
+
84
+ ## Tier C — unbound actions (~40–70 lines, feature decision)
85
+
86
+ 12 registered actions are never bound to a key, never called from code, and not
87
+ referenced in the default custom.rb. They remain reachable through the
88
+ action-search palette (`, , s`), so deleting them removes (obscure) features,
89
+ not just dead code — prune to taste:
90
+
91
+ `fhist_remove_nonexisting` (file_history.rb); from key_actions.rb: `eval_buf`,
92
+ `refresh_colors`, `gui_ensure_cursor_visible`, `close_all_buffers` (refs=0 —
93
+ its proc body references a method that doesn't exist), `refresh_func_panel`,
94
+ `V_to_latex_itemize`, `invoke_grep_search` (registered twice),
95
+ `execute_current_line_in_terminal_autoclose`, `delete_current_file`,
96
+ `buf_backup`, `debug_buf_hex`.
97
+
98
+ Check each proc body for helper functions that become orphaned once the action
99
+ is gone (then re-run the tier-A style scan).
100
+
101
+ ## Tier D — commented-out code sweep (optional, ~390 lines)
102
+
103
+ Heuristic count of comment lines that look like code (assignments, method
104
+ calls, `signal_connect`, old `require`s): ~391 across lib/, concentrated in
105
+ buffer.rb (52), key_binding_tree.rb (48), key_bindings_vimlike.rb (42),
106
+ gui_sourceview.rb (38), gui.rb (27). Much of it is pre-GTK4 leftovers
107
+ (`#TODO:gtk4`) and abandoned experiments. This contradicts the repo's
108
+ "match the surrounding style" convention, so do it only as a deliberate,
109
+ per-file pass — keep comments that document intent (e.g. the guarded-binding
110
+ ordering notes), delete only mechanical dead code. Git history preserves
111
+ everything.
112
+
113
+ ## Verification
114
+
115
+ - After each tier: `ruby exe/run_tests.rb --headless` (full suite).
116
+ - Tier B: verify `C , t r` is unbound (or repointed) and startup is clean with
117
+ scheme "vim" and "notepad" too (`cnf.keybindings.scheme`).
118
+ - Tier A langservp/editor items: open a Ruby file with LSP enabled once.
119
+ - Final: `wc -l lib/vimamsa/*.rb` before/after; one commit per tier.
120
+ - Also delete the superseded local scan reports (not in the repo).
@@ -0,0 +1,296 @@
1
+ # Plan: better Vim compatibility
2
+
3
+ TODO: act next on item 1 of "Order of work": the shared `VIM_BINDINGS` table,
4
+ loading its non-conflicting entries into vimlike. Then step 1, the operator +
5
+ motion layer. When an item is finished, move it to the DONE section at the end
6
+ of this document with a short summary and the git ref(s).
7
+
8
+ Goal: someone who knows Vim can start using Vimamsa without relearning basic
9
+ editing.
10
+
11
+ The `vim` keymap (`lib/vimamsa/key_bindings_vim.rb`) is the reference
12
+ implementation of Vim behavior. The default `vimlike` keymap
13
+ (`lib/vimamsa/key_bindings_vimlike.rb`) gets **every Vim binding that doesn't
14
+ conflict with a binding vimlike already has**. A generated report records
15
+ every conflict (see "Conflicts" below).
16
+
17
+ [missing_vim_bindings.md](missing_vim_bindings.md) lists what is missing
18
+ today. This file says what to build, and in which order.
19
+
20
+ ## Why the grammar matters most
21
+
22
+ Today each key combination is bound by hand (`C d e`, `C c w`, `C y $`, ...).
23
+ Vim users don't memorize those combinations. They combine an operator, a count
24
+ and a motion. Any combination nobody wrote out does nothing, and users notice
25
+ that within minutes. So the first and biggest step is a general
26
+ operator + motion layer. Most of the later steps build on it.
27
+
28
+ ## Shared Vim bindings
29
+
30
+ The Vim actions and the binding table go in shared code, for example
31
+ `lib/vimamsa/vim_core.rb` (actions, motions, operators, text objects) and a
32
+ table `VIM_BINDINGS` of `key => action`. The two keymaps use the table
33
+ differently:
34
+
35
+ - **`vim` keymap:** binds the whole table.
36
+ - **`vimlike` keymap:** loads its own bindings first, then binds each table
37
+ entry that doesn't conflict with them. Entries that conflict are skipped.
38
+ Vimlike's own bindings always win, so existing users see no change in
39
+ behavior.
40
+
41
+ "Conflict" is decided by a function, not by hand (see the next section). New
42
+ Vim bindings therefore show up in vimlike automatically, unless they clash.
43
+
44
+ ## Conflicts: definition and automatic report
45
+
46
+ ### What counts as a conflict
47
+
48
+ The check and its report are done (see DONE); the definition below is the
49
+ rule that loading the shared table into vimlike must follow.
50
+
51
+ A Vim binding `M k1 k2 ... kn` (mode `M`) conflicts with vimlike when one of
52
+ these holds:
53
+
54
+ 1. **Same keys, different action:** vimlike binds exactly the same key sequence
55
+ in mode `M` to something else. Example: `C s` is `easy_jump` in vimlike
56
+ but "substitute character" in Vim.
57
+ 2. **A vimlike binding is a prefix of the Vim one:** vimlike binds a shorter
58
+ sequence that runs at once, so the Vim sequence can never be reached.
59
+ Example: vimlike `C z` (start browse mode) blocks `z t`, `z z` and `z b`.
60
+ 3. **The Vim binding is a prefix of vimlike ones:** for example, vimlike's
61
+ `,` is a leader key with dozens of `, x` bindings, so Vim's `,` (repeat
62
+ `f`/`t` backwards) can't be bound. The same goes for `space`, which starts
63
+ `C space <char>`.
64
+
65
+ Bindings for the same action, or ones that agree in meaning, are "shared",
66
+ not conflicts.
67
+
68
+ The check walks the real `KeyBindingTree` after vimlike has loaded, so it
69
+ always matches the code. It is not a hand-kept list.
70
+
71
+ ### Known conflicts, for orientation
72
+
73
+ These are from reading the code; the report is the authority:
74
+
75
+ | Keys (Command mode) | vimlike | Vim |
76
+ | ------------------------- | ------------------------------ | ---------------------------- |
77
+ | `s` | easy_jump | substitute char |
78
+ | `C` | content search | change to end of line |
79
+ | `X` | open line below | delete char before cursor |
80
+ | `,` | leader prefix | repeat `f`/`t` backwards |
81
+ | `space` | `space <char>` insert prefix | move right |
82
+ | `z` | start browse mode | `zz`, `zt`, `zb`, folds |
83
+ | `tab` | switch to last buffer | jump forward (`ctrl-i`) |
84
+ | `V`, `ctrl-v` | other actions | linewise / block visual |
85
+
86
+ ## Steps, in priority order
87
+
88
+ ### 1. Operator + motion layer
89
+
90
+ - **Motions** are objects that, given a buffer, a position and a count, return
91
+ a target position. Each one is also marked:
92
+ - charwise or linewise (`j`, `k`, `G` and `gg` are linewise),
93
+ - inclusive or exclusive (`e` and `f` are inclusive; `w` and `b` are exclusive).
94
+ - **Operators** (`d c y > < = gu gU g~ gq`) take a range plus a
95
+ linewise/charwise flag and act on it. Doubling an operator (`dd`, `cc`, `>>`,
96
+ `gUU`) acts on `count` lines.
97
+ - **Counts** work on both and multiply: `3dw`, `d3w`, `2d3w`. Counts inside a
98
+ sequence already work where a binding has `<num>` (see DONE); the layer makes
99
+ them general.
100
+ - **Operator-pending state in `KeyBindingTree`.** After an operator key, the
101
+ next keys are read as a motion or text object, with an optional count. `esc`
102
+ cancels.
103
+ - The same motion objects drive plain cursor movement and Visual-mode extension,
104
+ so each motion is written only once.
105
+ - Keep `cw` behaving like `ce`, and keep `dw` stopping at the end of the line,
106
+ as in Vim.
107
+ - Replace the hand-made bindings (`C d e`, `C c w`, `C y $`, ...) with the
108
+ generic layer.
109
+
110
+ The conflict check applies inside operator-pending state too. When vimlike
111
+ binds `d <x>` to something of its own, that wins, and the report lists it.
112
+
113
+ ### 2. Missing motions
114
+
115
+ - `t` / `T`, with `;` and `,` repeating them.
116
+ - `%`.
117
+ - `?`, and `#` for the word under the cursor.
118
+ - `W B E ge gE`.
119
+ - `{ }` and `( )`.
120
+ - `H M L`.
121
+ - Half-page `ctrl-d` / `ctrl-u`; `ctrl-e` / `ctrl-y`; `zt zz zb`.
122
+
123
+ Most of these are small once step 1 exists. The ones that don't conflict
124
+ (`t`, `%`, `W`, `{`, ...) go into vimlike too.
125
+
126
+ ### 3. Visual modes
127
+
128
+ - Linewise `V` and blockwise `ctrl-v`. Block mode needs `I` / `A` for inserting
129
+ text on many lines at once.
130
+ - `o` (go to the other end of the selection) and `gv` (select the last area again).
131
+ - Visual mode applies operators through the step 1 layer (`V>`, `vgU`, ...).
132
+
133
+ In vimlike, `V` and `ctrl-v` already have other uses, so they are conflicts.
134
+ The modes themselves are still shared code, and vimlike can reach them
135
+ through other keys if wanted.
136
+
137
+ ### 4. Registers, put, repeat and undo
138
+
139
+ - Registers remember whether text was yanked linewise or charwise. After `yy`
140
+ or `dd`, `p` / `P` puts it below or above the line, not at the cursor.
141
+ - Registers: named (`"a`–`"z`, with `"A` appending), unnamed `""`, yank `"0`,
142
+ numbered `"1`–`"9`, clipboard `"+` / `"*`, and black hole `"_`. Also
143
+ `ctrl-r x` in Insert mode.
144
+ - `.` repeats the last change exactly: the operator, the motion and count, and
145
+ any text typed in Insert mode. Recording changes as data (step 1) makes this
146
+ possible.
147
+ - One Insert-mode session (`i...esc`) is one undo step.
148
+
149
+ ### 5. Ex commands
150
+
151
+ Extend `lib/vimamsa/gui_command_line.rb`, which already handles `:w :q :wq :e :42 :!`:
152
+
153
+ - `:s/pat/rep/flags` with ranges: `%`, `.`, `$`, `N,M`, `'<,'>`. This comes first.
154
+ - `:noh`, `:x`, `:wa`, `:qa`.
155
+ - `:bn`, `:bp`, `:bd`, `:b N`.
156
+ - `:<range>d`, `:<range>y`, `:<range>>`, `:g/pat/cmd`, `:v/pat/cmd`.
157
+ - `:set` for common options, mapped onto `cnf`: `ts`, `sw`, `et`, `nu`,
158
+ `wrap`, `ic`, `scs`.
159
+ - Translate Vim regex syntax (`\<`, `\>`, `\(`, `\)`, `\v`) to Ruby regex.
160
+
161
+ The command line already runs Ruby code as a fallback. Vim commands must be
162
+ tried first, and Ruby only when nothing matches. The command line is shared,
163
+ so this applies to both keymaps.
164
+
165
+ ### 6. Smaller habits
166
+
167
+ - A real jumplist: `ctrl-o` / `ctrl-i` and ``` `` ```.
168
+ - `gi`, `gJ`, `ctrl-x` (decrement), `gq`.
169
+ - Insert mode: `ctrl-w`, `ctrl-u`, `ctrl-o {cmd}`.
170
+
171
+ ## Supporting work
172
+
173
+ ### Differential tests against real Vim
174
+
175
+ A vim-compatibility test suite (for example
176
+ `tests/test_vim_compat.rb`) runs each case in both editors and compares the
177
+ buffer text and cursor position:
178
+
179
+ ```sh
180
+ vim -Nu NONE -i NONE -es -c 'exe "norm! <keys>"' -c 'wq' file
181
+ ```
182
+
183
+ A case is just `(start text, start cursor, keys)`, so one table can hold
184
+ hundreds of cases. Skip the suite when `vim` isn't installed.
185
+
186
+ - Run every case with the `vim` keymap.
187
+ - Also run it with `vimlike`, except for cases whose keys are in the
188
+ generated conflict list. That proves the shared bindings behave the same in
189
+ both keymaps.
190
+
191
+ Done so far for text objects only (see DONE); the general suite is open.
192
+
193
+ This makes "compatible" something the tests measure, and it catches the
194
+ off-by-one edge cases (`$`, `e` at the end of a word, `cw`, linewise put) that
195
+ reading the code misses.
196
+
197
+ ### Onboarding
198
+
199
+ - **First run:** ask whether to use "Vim keys" or "Vimamsa keys". Today a
200
+ Vim user has to find the scheme setting on their own.
201
+ - **A "differences from Vim" page:** a short list of the deliberate
202
+ differences in the `vim` keymap, built from the header comment of
203
+ `key_bindings_vim.rb`. For vimlike, the generated conflict report already
204
+ covers this. Reach both through `:help vim` or the Help menu.
205
+ - **Optional:** read simple mappings (`nnoremap`, `inoremap` and `vnoremap`
206
+ lines only) from `~/.vimrc`, or from a `~/.vimamsa/vimrc`, so personal
207
+ mappings carry over.
208
+
209
+ ### Investigate: switching keymap without restart
210
+
211
+ Today the scheme (`cnf.keybindings.scheme`) is read once in `Editor#start`, and
212
+ changing it needs a restart. Find out whether a switch at runtime (from
213
+ Settings, or `:set keymap=vim`) is feasible, and what it would break:
214
+
215
+ - **Rebuilding the tree:** a new `KeyBindingTree` must be built, and then
216
+ every binding made after the scheme file must be added again. That includes
217
+ module bindings (`search_replace.rb`, `file_manager.rb`, buffer manager,
218
+ bookmarks, diff view), plugins and both phases of `custom.rb`. They are now
219
+ scattered `bindkey` calls run once at startup. They would need to be
220
+ replayable, either by recording every `bindkey` call with its origin or by
221
+ giving each module a `bind_keys` hook.
222
+ - **Actions:** scheme files register actions (`reg_act`) and define helper
223
+ methods (`_insert_move`, ...) with the same names in both schemes. Leftovers
224
+ from the old scheme stay in `vma.actions`, and redefinitions overwrite each
225
+ other. Scheme-only actions would need to be namespaced or unregistered.
226
+ - **Global side effects:** scheme files also set `cnf.mode.*` cursor colors,
227
+ which overwrites what the user set in `custom.rb`.
228
+ - **Live state:** the current mode, a half-typed key sequence, a pending
229
+ count, macro recording, minor modes on open buffers (`fexp`, `grep`,
230
+ `bmgr`) and `vma.kbd` listeners (`setup_kbd_handlers`) all point into the
231
+ old tree. The switch has to happen from a clean state: Command mode, no
232
+ pending keys, listeners moved to the new tree.
233
+ - **Things that cache bindings:** the menu labels (`act_bindings`), the key
234
+ binding help buffer and the conflict report must be rebuilt.
235
+ - **Macros and muscle memory:** recorded macros are key sequences, so they
236
+ mean something else in the other scheme.
237
+ - **Tests:** tests assume vimlike (`--test` forces it). A switch test would
238
+ check that bindings, modes and the user's custom bindings survive vimlike →
239
+ vim → vimlike.
240
+
241
+ The sandbox loader written for the conflict report (it loads a scheme file
242
+ into a separate tree and restores the actions, methods and `cnf` it touches)
243
+ is a first step and shows which side effects exist. The outcome of the
244
+ investigation is a short note: feasible as is, feasible after a refactor (say
245
+ which), or keep the restart.
246
+
247
+ ## Order of work
248
+
249
+ 1. Move the existing Vim bindings into the shared table. Load the
250
+ non-conflicting ones into vimlike. This is small, and it defines the rules
251
+ for everything after. (The conflict report and its test are done.)
252
+ 2. The operator-pending layer, ported motions, and the differential test suite.
253
+ Port the existing hand-made bindings first, so nothing gets worse. This
254
+ includes the text object bindings, which are bound per operator for now.
255
+ 3. Registers that remember linewise text, and linewise put.
256
+ 4. Missing motions.
257
+ 5. `V` and `ctrl-v`.
258
+ 6. `.` repeat, and undo grouping for Insert sessions.
259
+ 7. `:s` with ranges, then the other Ex commands.
260
+ 8. Onboarding: the first-run question and the differences page.
261
+ 9. Step 6 items and `.vimrc` import.
262
+ 10. The investigation into switching keymaps without restart. It can run any
263
+ time; the sandbox loader it builds on exists.
264
+
265
+ Each step regenerates `doc/vimlike_vim_conflicts.md` and updates
266
+ `missing_vim_bindings.md` and the header comment of `key_bindings_vim.rb`.
267
+
268
+ ## DONE
269
+
270
+ - **Conflict report** (2026-11-18, `b7d113a`): `vim_binding_conflicts` in
271
+ `key_bindings_report.rb` loads both keymap files into separate key trees (a
272
+ sandbox loader that restores `vma.kbd`, actions, helper methods and cursor
273
+ colors) and classifies each vim binding as shared, missing from vimlike, or
274
+ a conflict (same keys with another action, blocked by a shorter vimlike
275
+ binding, vimlike uses the keys as a prefix, or taken by a `<char>` binding).
276
+ Bindings that run the same code count as shared. The report is
277
+ `doc/vimlike_vim_conflicts.md`, regenerated with
278
+ `VMA_UPDATE_DOC=1 ruby exe/run_tests.rb --headless vim_conflicts`;
279
+ `tests/test_vim_conflicts.rb` fails when it is out of date. Help menu:
280
+ "Vim keys that differ in vimlike". Differs from the plan: no "Added to
281
+ vimlike" group yet (needs the shared table), and "Not implemented" lists
282
+ only vim-keymap bindings missing from vimlike, not a full reference list.
283
+ - **Text objects** (2026-11-18, `4c5ed8b`): `lib/vimamsa/text_objects.rb`.
284
+ `iw aw iW aW is as ip ap`, quotes (`" ' \``), brackets `( [ { <` with the
285
+ `b`/`B` aliases, and `it`/`at`, after `d c y gU gu g~` and in Visual mode, in
286
+ both keymaps. Follows vim 9.1, including the white space `aw`/`a"` take,
287
+ linewise inner blocks, `di(` using the next block on the line, and a count
288
+ before the operator (`2di(`). Bound per operator for now, not through the
289
+ operator-pending layer (step 1).
290
+ - **Differential test against real vim, text objects** (2026-11-18, `4c5ed8b`,
291
+ `e464117`): `tests/test_text_objects.rb` holds 57 cases with vim's results
292
+ and re-checks them against `vim -Nu NONE -es` when vim is installed. The
293
+ test VM now installs vim, so the check runs there.
294
+ - **Count inside a key sequence** (2026-11-19, `2e9fb0b`): `d 3 e` works, and
295
+ any binding with `<num>`. The count multiplies one typed before the
296
+ sequence (`2 d 3 e` = 6). A first piece of the counts in step 1.