Add the scope visualizer

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/scope-visualizer.md

@@ -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)

packages/cheatsheet/src/lib/sampleSpokenFormInfos/defaults.json

@@ -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",

packages/common/src/cursorlessCommandIds.ts

@@ -43,6 +43,8 @@ export const cursorlessCommandIds = [
   "cursorless.showQuickPick",
   "cursorless.takeSnapshot",
   "cursorless.toggleDecorations",
+  "cursorless.showScopeVisualizer",
+  "cursorless.hideScopeVisualizer",
 ] as const satisfies readonly `cursorless.${string}`[];
 
 export type CursorlessCommandId = (typeof cursorlessCommandIds)[number];
@@ -104,4 +106,10 @@ export const cursorlessCommandDescriptions: Record<
   ["cursorless.keyboard.modal.modeToggle"]: new HiddenCommand(
     "Toggle the cursorless modal mode",
   ),
+  ["cursorless.showScopeVisualizer"]: new HiddenCommand(
+    "Show the scope visualizer",
+  ),
+  ["cursorless.hideScopeVisualizer"]: new HiddenCommand(
+    "Hide the scope visualizer",
+  ),
 };

packages/common/src/testUtil/toPlainObject.ts

@@ -7,8 +7,6 @@ import type {
 } from "..";
 import { FlashStyle, isLineRange } from "..";
 import { Token } from "../types/Token";
-import { Position } from "../types/Position";
-import { Range } from "../types/Range";
 import { Selection } from "../types/Selection";
 
 export type PositionPlainObject = {
@@ -85,7 +83,23 @@ export type SerializedMarks = {
   [decoratedCharacter: string]: RangePlainObject;
 };
 
-export function rangeToPlainObject(range: Range): RangePlainObject {
+/**
+ * Simplified Position interface containing only what we need for serialization
+ */
+interface SimplePosition {
+  line: number;
+  character: number;
+}
+
+/**
+ * Simplified Range interface containing only what we need for serialization
+ */
+interface SimpleRange {
+  start: SimplePosition;
+  end: SimplePosition;
+}
+
+export function rangeToPlainObject(range: SimpleRange): RangePlainObject {
   return {
     start: positionToPlainObject(range.start),
     end: positionToPlainObject(range.end),
@@ -104,7 +118,7 @@ export function selectionToPlainObject(
 export function positionToPlainObject({
   line,
   character,
-}: Position): PositionPlainObject {
+}: SimplePosition): PositionPlainObject {
   return { line, character };
 }
 

packages/cursorless-vscode-e2e/src/suite/scopeVisualizer/checkAndResetFakes.ts

@@ -0,0 +1,39 @@
+import { assert } from "chai";
+import * as sinon from "sinon";
+import {
+  createDecorationTypeCallToPlainObject,
+  setDecorationsCallToPlainObject,
+} from "./spyCallsToPlainObject";
+import { Fakes, ExpectedArgs } from "./scopeVisualizerTest.types";
+
+export function checkAndResetFakes(fakes: Fakes, expected: ExpectedArgs) {
+  const actual = getSpyCallsAndResetFakes(fakes);
+  assert.deepStrictEqual(actual, expected, JSON.stringify(actual));
+}
+
+function getSpyCallsAndResetFakes({
+  createTextEditorDecorationType,
+  setDecorations,
+  dispose,
+}: Fakes) {
+  return {
+    decorationRenderOptions: getAndResetFake(
+      createTextEditorDecorationType,
+      createDecorationTypeCallToPlainObject,
+    ),
+    decorationRanges: getAndResetFake(
+      setDecorations,
+      setDecorationsCallToPlainObject,
+    ),
+    disposedDecorationIds: getAndResetFake(dispose, ({ args: [id] }) => id),
+  };
+}
+
+function getAndResetFake<ArgList extends any[], Return, Expected>(
+  spy: sinon.SinonSpy<ArgList, Return>,
+  transform: (call: sinon.SinonSpyCall<ArgList, Return>) => Expected,
+) {
+  const actual = spy.getCalls().map(transform);
+  spy.resetHistory();
+  return actual;
+}

packages/cursorless-vscode-e2e/src/suite/scopeVisualizer/colorConfig.ts

@@ -0,0 +1,53 @@
+import { ScopeVisualizerColorConfig } from "@cursorless/vscode-common";
+
+/**
+ * Fake color config to use for testing. We use an alpha of 50% and try to use
+ * different rgb channels where possible to make it easier to see what happens
+ * when we blend colors.
+ */
+export const COLOR_CONFIG: ScopeVisualizerColorConfig = {
+  dark: {
+    content: {
+      background: "#00000180",
+      borderPorous: "#00000280",
+      borderSolid: "#00000380",
+    },
+    domain: {
+      background: "#01000080",
+      borderPorous: "#02000080",
+      borderSolid: "#03000080",
+    },
+    iteration: {
+      background: "#00000480",
+      borderPorous: "#00000580",
+      borderSolid: "#00000680",
+    },
+    removal: {
+      background: "#00010080",
+      borderPorous: "#00020080",
+      borderSolid: "#00030080",
+    },
+  },
+  light: {
+    content: {
+      background: "#00000180",
+      borderPorous: "#00000280",
+      borderSolid: "#00000380",
+    },
+    domain: {
+      background: "#01000080",
+      borderPorous: "#02000080",
+      borderSolid: "#03000080",
+    },
+    iteration: {
+      background: "#00000480",
+      borderPorous: "#00000580",
+      borderSolid: "#00000680",
+    },
+    removal: {
+      background: "#00010080",
+      borderPorous: "#00020080",
+      borderSolid: "#00030080",
+    },
+  },
+};