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

cursorless-talon/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",

cursorless-talon/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()
+                ],
+            ],
+        },
+    ]

cursorless-talon/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()

cursorless-talon/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)

docs/user/README.md

@@ -143,7 +143,7 @@ Note that if the mark is `"this"`, and you have multiple cursors, the modifiers
 
 ##### Syntactic scopes
 
-For programming languages where Cursorless has rich parse tree support, we support modifiers that expand to the nearest containing function, class, etc. See [the source code](../../queries) for a list of supported languages. Some languages are still supported using our legacy implementation; those will be listed in [here](../../packages/cursorless-engine/src/languages/LegacyLanguageId.ts). Below is a list of supported scope types, keeping in mind that this table can sometimes lag behind the actual list. Your cheatsheet (say `"cursorless cheatsheet"` with VSCode focused) will have the most up-to-date list.
+For programming languages where Cursorless has rich parse tree support, we support modifiers that expand to the nearest containing function, class, etc. See [the source code](../../queries) for a list of supported languages. Some languages are still supported using our legacy implementation; those will be listed in [here](../../packages/cursorless-engine/src/languages/LegacyLanguageId.ts). Below is a list of supported scope types, keeping in mind that this table can sometimes lag behind the actual list. Your cheatsheet (say `"cursorless cheatsheet"` with VSCode focused) will have the most up-to-date list. It can also be helpful to use the [scope visualizer](./scope-visualizer.md) to visualize the scope types on your own code.
 
 | Term           | Syntactic element                                   |
 | -------------- | --------------------------------------------------- |

docs/user/images/visualize-block-removal.png

@@ -0,0 +1,23 @@
+# Scope visualizer
+
+The scope visualizer allows you to visualize Cursorless scopes on your code in real time. It is useful to understand how Cursorless scopes work, and is also useful for Cursorless contributors as they develop new scopes.
+
+## Usage
+
+To start the scope visualizer, say `"visualize <scope>"`, where `<scope>` is the name of the scope you want to visualize. For example, `"visualize funk"`. To stop the scope visualizer, say `"visualize nothing"`.
+
+You can also visualize removal and iteration ranges for scopes by saying `"visualize <scope> removal"` and `"visualize <scope> iteration"`, respectively.
+
+## Examples
+
+### `"visualize funk"`
+
+![visualize funk](images/visualize-funk.png)
+
+### `"visualize token"`
+
+![visualize token](images/visualize-token.png)
+
+### `"visualize block removal"`
+
+![visualize block removal](images/visualize-block-removal.png)

docs/user/images/visualize-funk.png

@@ -1030,6 +1030,40 @@
         }
       ]
     },
+    {
+      "name": "Scope visualizer",
+      "id": "scopeVisualizer",
+      "items": [
+        {
+          "id": "hideScopeVisualizer",
+          "type": "command",
+          "variations": [
+            {
+              "spokenForm": "visualize nothing",
+              "description": "Hide scope visualizer"
+            }
+          ]
+        },
+        {
+          "id": "show_scope_visualizer",
+          "type": "command",
+          "variations": [
+            {
+              "spokenForm": "visualize <scope>",
+              "description": "Visualize <scope>"
+            },
+            {
+              "spokenForm": "visualize <scope> removal",
+              "description": "Visualize <scope> removal range"
+            },
+            {
+              "spokenForm": "visualize <scope> iteration",
+              "description": "Visualize <scope> iteration range"
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "Scopes",
       "id": "scopes",
@@ -1374,6 +1408,16 @@
             }
           ]
         },
+        {
+          "id": "sentence",
+          "type": "scopeType",
+          "variations": [
+            {
+              "spokenForm": "sentence",
+              "description": "Sentence"
+            }
+          ]
+        },
         {
           "id": "statement",
           "type": "scopeType",