Add the scope visualizer (#1653)

- Depends on #1651
- Depends on #1652
- Depends on #1649
- Depends on #1644
## Checklist

- [x] Add image to doc page
- [x] File issue to migrate all our vscode references to use new thin
wrapper
- [x] File issue about reworking removal highlight range to return
generalised range, and not using line range for line target content
range
- [x] Investigate cheatsheet performance issue
- [x] Migrate todos from #1523 
- [x] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [x] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [x] I have not broken the cheatsheet
- [x] Compute border colors from background color?

---------

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>

Author: pokey

src/cheatsheet/cheat_sheet.py

@@ -7,6 +7,7 @@
 from .get_list import get_list, get_lists
 from .sections.actions import get_actions
 from .sections.compound_targets import get_compound_targets
+from .sections.get_scope_visualizer import get_scope_visualizer
 from .sections.modifiers import get_modifiers
 from .sections.scopes import get_scopes
 from .sections.special_marks import get_special_marks
@@ -102,6 +103,11 @@ def cursorless_cheat_sheet_get_json():
                 "id": "scopes",
                 "items": get_scopes(),
             },
+            {
+                "name": "Scope visualizer",
+                "id": "scopeVisualizer",
+                "items": get_scope_visualizer(),
+            },
             {
                 "name": "Modifiers",
                 "id": "modifiers",

src/cheatsheet/sections/get_scope_visualizer.py

@@ -0,0 +1,27 @@
+from ..get_list import get_list, get_raw_list, make_readable
+
+
+def get_scope_visualizer():
+    show_scope_visualizer = list(get_raw_list("show_scope_visualizer").keys())[0]
+    visualization_types = get_raw_list("visualization_type")
+
+    return [
+        *get_list("hide_scope_visualizer", "command"),
+        {
+            "id": "show_scope_visualizer",
+            "type": "command",
+            "variations": [
+                {
+                    "spokenForm": f"{show_scope_visualizer} <scope>",
+                    "description": "Visualize <scope>",
+                },
+                *[
+                    {
+                        "spokenForm": f"{show_scope_visualizer} <scope> {spoken_form}",
+                        "description": f"Visualize <scope> {make_readable(id).lower()} range",
+                    }
+                    for spoken_form, id in visualization_types.items()
+                ],
+            ],
+        },
+    ]

src/cursorless.talon

@@ -20,3 +20,8 @@ tag: user.cursorless
     user.cursorless_wrap(cursorless_wrap_action, cursorless_target, cursorless_wrapper)
 
 {user.cursorless_homophone} settings: user.cursorless_show_settings_in_ide()
+
+{user.cursorless_show_scope_visualizer} <user.cursorless_scope_type> [{user.cursorless_visualization_type}]:
+    user.private_cursorless_show_scope_visualizer(cursorless_scope_type, cursorless_visualization_type or "content")
+{user.cursorless_hide_scope_visualizer}:
+    user.private_cursorless_hide_scope_visualizer()

src/scope_visualizer.py

@@ -0,0 +1,48 @@
+from talon import Module, app
+
+from .csv_overrides import init_csv_and_watch_changes
+from .cursorless_command_server import run_rpc_command_no_wait
+
+mod = Module()
+mod.list("cursorless_show_scope_visualizer", desc="Show scope visualizer")
+mod.list("cursorless_hide_scope_visualizer", desc="Hide scope visualizer")
+mod.list(
+    "cursorless_visualization_type",
+    desc='Cursorless visualization type, e.g. "removal" or "iteration"',
+)
+
+# NOTE: Please do not change these dicts.  Use the CSVs for customization.
+# See https://www.cursorless.org/docs/user/customization/
+visualization_types = {
+    "removal": "removal",
+    "iteration": "iteration",
+}
+
+
+@mod.action_class
+class Actions:
+    def private_cursorless_show_scope_visualizer(
+        scope_type: dict, visualization_type: str
+    ):
+        """Shows scope visualizer"""
+        run_rpc_command_no_wait(
+            "cursorless.showScopeVisualizer", scope_type, visualization_type
+        )
+
+    def private_cursorless_hide_scope_visualizer():
+        """Hides scope visualizer"""
+        run_rpc_command_no_wait("cursorless.hideScopeVisualizer")
+
+
+def on_ready():
+    init_csv_and_watch_changes(
+        "scope_visualizer",
+        {
+            "show_scope_visualizer": {"visualize": "showScopeVisualizer"},
+            "hide_scope_visualizer": {"visualize nothing": "hideScopeVisualizer"},
+            "visualization_type": visualization_types,
+        },
+    )
+
+
+app.register("ready", on_ready)