Changes to prepare for tutorial (#2525)

## Checklist

- [-] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [-] 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)
- [-] I have not broken the cheatsheet

Author: pokey

packages/cursorless-engine/src/core/Debouncer.ts renamed to packages/common/src/Debouncer.ts

@@ -1,5 +1,3 @@
-import { ide } from "../singletons/ide.singleton";
-
 /**
  * Debounces a callback.  Uses the `decorationDebounceDelayMs` configuration
  * value to determine the debounce delay.
@@ -10,7 +8,7 @@ export class Debouncer {
   constructor(
     /** The callback to debounce */
     private callback: () => void,
-    private debounceDelayMs?: number,
+    private debounceDelayMs: number,
   ) {
     this.run = this.run.bind(this);
   }
@@ -20,14 +18,10 @@ export class Debouncer {
       clearTimeout(this.timeoutHandle);
     }
 
-    const decorationDebounceDelayMs =
-      this.debounceDelayMs ??
-      ide().configuration.getOwnConfiguration("decorationDebounceDelayMs");
-
     this.timeoutHandle = setTimeout(() => {
       this.callback();
       this.timeoutHandle = null;
-    }, decorationDebounceDelayMs);
+    }, this.debounceDelayMs);
   }
 
   dispose() {

packages/common/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./cursorlessCommandIds";
 export * from "./cursorlessSideBarIds";
+export * from "./Debouncer";
 export * from "./errors";
 export * from "./extensionDependencies";
 export * from "./FakeCommandServerApi";

packages/cursorless-engine/src/KeyboardTargetUpdater.ts

@@ -1,19 +1,23 @@
-import { Disposable } from "@cursorless/common";
-import { Debouncer } from "./core/Debouncer";
+import { Disposable, IDE } from "@cursorless/common";
 import { StoredTargetMap } from "./core/StoredTargets";
 import { CursorStage } from "./processTargets/marks/CursorStage";
-import { ide } from "./singletons/ide.singleton";
+import { DecorationDebouncer } from "./util/DecorationDebouncer";
 
 export class KeyboardTargetUpdater {
   private disposables: Disposable[] = [];
   private selectionWatcherDisposable: Disposable | undefined;
-  private debouncer: Debouncer;
-
-  constructor(private storedTargets: StoredTargetMap) {
-    this.debouncer = new Debouncer(() => this.updateKeyboardTarget());
+  private debouncer: DecorationDebouncer;
+
+  constructor(
+    private ide: IDE,
+    private storedTargets: StoredTargetMap,
+  ) {
+    this.debouncer = new DecorationDebouncer(ide.configuration, () =>
+      this.updateKeyboardTarget(),
+    );
 
     this.disposables.push(
-      ide().configuration.onDidChangeConfiguration(() => this.maybeActivate()),
+      ide.configuration.onDidChangeConfiguration(() => this.maybeActivate()),
 
       this.debouncer,
     );
@@ -22,15 +26,14 @@ export class KeyboardTargetUpdater {
   }
 
   maybeActivate(): void {
-    const isActive = ide().configuration.getOwnConfiguration(
+    const isActive = this.ide.configuration.getOwnConfiguration(
       "experimental.keyboardTargetFollowsSelection",
     );
 
     if (isActive) {
       if (this.selectionWatcherDisposable == null) {
-        this.selectionWatcherDisposable = ide().onDidChangeTextEditorSelection(
-          this.debouncer.run,
-        );
+        this.selectionWatcherDisposable =
+          this.ide.onDidChangeTextEditorSelection(this.debouncer.run);
       }
 
       return;
@@ -43,7 +46,7 @@ export class KeyboardTargetUpdater {
   }
 
   private updateKeyboardTarget() {
-    const activeEditor = ide().activeTextEditor;
+    const activeEditor = this.ide.activeTextEditor;
 
     if (activeEditor == null || this.storedTargets.get("keyboard") == null) {
       return;

packages/cursorless-engine/src/api/CursorlessEngineApi.ts

@@ -1,10 +1,15 @@
 import type {
+  ActionType,
   Command,
+  CommandComplete,
   CommandResponse,
+  Disposable,
   HatTokenMap,
   IDE,
   ReadOnlyHatMap,
   ScopeProvider,
+  ScopeType,
+  SpokenForm,
 } from "@cursorless/common";
 import type { CommandRunner } from "../CommandRunner";
 import type { StoredTargetMap } from "../core/StoredTargets";
@@ -29,7 +34,12 @@ export interface CustomSpokenFormGenerator {
    */
   readonly needsInitialTalonUpdate: boolean | undefined;
 
-  onDidChangeCustomSpokenForms: (listener: () => void) => void;
+  onDidChangeCustomSpokenForms(listener: () => void): Disposable;
+
+  commandToSpokenForm(command: CommandComplete): SpokenForm;
+  scopeTypeToSpokenForm(scopeType: ScopeType): SpokenForm;
+  actionIdToSpokenForm(actionId: ActionType): SpokenForm;
+  graphemeToSpokenForm(grapheme: string): SpokenForm;
 }
 
 export interface CommandApi {

packages/cursorless-engine/src/core/HatAllocator.ts

@@ -2,48 +2,49 @@ import type { Disposable, Hats, TokenHat } from "@cursorless/common";
 import { ide } from "../singletons/ide.singleton";
 import tokenGraphemeSplitter from "../singletons/tokenGraphemeSplitter.singleton";
 import { allocateHats } from "../util/allocateHats";
-import { Debouncer } from "./Debouncer";
 import { IndividualHatMap } from "./IndividualHatMap";
+import { DecorationDebouncer } from "../util/DecorationDebouncer";
 
 interface Context {
   getActiveMap(): Promise<IndividualHatMap>;
 }
 
 export class HatAllocator {
   private disposables: Disposable[] = [];
-  private debouncer = new Debouncer(() => this.allocateHats());
 
   constructor(
     private hats: Hats,
     private context: Context,
   ) {
     ide().disposeOnExit(this);
 
+    const debouncer = new DecorationDebouncer(ide().configuration, () =>
+      this.allocateHats(),
+    );
+
     this.disposables.push(
-      this.hats.onDidChangeEnabledHatStyles(this.debouncer.run),
-      this.hats.onDidChangeIsEnabled(this.debouncer.run),
+      this.hats.onDidChangeEnabledHatStyles(debouncer.run),
+      this.hats.onDidChangeIsEnabled(debouncer.run),
 
       // An event that fires when a text document opens
-      ide().onDidOpenTextDocument(this.debouncer.run),
+      ide().onDidOpenTextDocument(debouncer.run),
       // An event that fires when a text document closes
-      ide().onDidCloseTextDocument(this.debouncer.run),
+      ide().onDidCloseTextDocument(debouncer.run),
       // An Event which fires when the active editor has changed. Note that the event also fires when the active editor changes to undefined.
-      ide().onDidChangeActiveTextEditor(this.debouncer.run),
+      ide().onDidChangeActiveTextEditor(debouncer.run),
       // An Event which fires when the array of visible editors has changed.
-      ide().onDidChangeVisibleTextEditors(this.debouncer.run),
+      ide().onDidChangeVisibleTextEditors(debouncer.run),
       // An event that is emitted when a text document is changed. This usually happens when the contents changes but also when other things like the dirty-state changes.
-      ide().onDidChangeTextDocument(this.debouncer.run),
+      ide().onDidChangeTextDocument(debouncer.run),
       // An Event which fires when the selection in an editor has changed.
-      ide().onDidChangeTextEditorSelection(this.debouncer.run),
+      ide().onDidChangeTextEditorSelection(debouncer.run),
       // An Event which fires when the visible ranges of an editor has changed.
-      ide().onDidChangeTextEditorVisibleRanges(this.debouncer.run),
+      ide().onDidChangeTextEditorVisibleRanges(debouncer.run),
       // Re-draw hats on grapheme splitting algorithm change in case they
       // changed their token hat splitting setting.
-      tokenGraphemeSplitter().registerAlgorithmChangeListener(
-        this.debouncer.run,
-      ),
+      tokenGraphemeSplitter().registerAlgorithmChangeListener(debouncer.run),
 
-      this.debouncer,
+      debouncer,
     );
   }
 

packages/cursorless-engine/src/cursorlessEngine.ts

@@ -41,7 +41,7 @@ import { ScopeSupportChecker } from "./scopeProviders/ScopeSupportChecker";
 import { ScopeSupportWatcher } from "./scopeProviders/ScopeSupportWatcher";
 import { injectIde } from "./singletons/ide.singleton";
 
-interface Props {
+export interface EngineProps {
   ide: IDE;
   hats?: Hats;
   treeSitterQueryProvider?: RawTreeSitterQueryProvider;
@@ -59,13 +59,13 @@ export async function createCursorlessEngine({
   commandServerApi = new DisabledCommandServerApi(),
   talonSpokenForms = new DisabledTalonSpokenForms(),
   snippets = new DisabledSnippets(),
-}: Props): Promise<CursorlessEngine> {
+}: EngineProps): Promise<CursorlessEngine> {
   injectIde(ide);
 
   const debug = new Debug(ide);
   const rangeUpdater = new RangeUpdater();
   const storedTargets = new StoredTargetMap();
-  const keyboardTargetUpdater = new KeyboardTargetUpdater(storedTargets);
+  const keyboardTargetUpdater = new KeyboardTargetUpdater(ide, storedTargets);
   const customSpokenFormGenerator = new CustomSpokenFormGeneratorImpl(
     talonSpokenForms,
   );

packages/cursorless-engine/src/generateSpokenForm/CustomSpokenFormGeneratorImpl.ts

@@ -56,7 +56,17 @@ export class CustomSpokenFormGeneratorImpl
   }
 
   actionIdToSpokenForm(actionId: ActionType) {
-    return this.customSpokenForms.spokenFormMap.action[actionId];
+    return this.spokenFormGenerator.getSpokenFormForSingleTerm(
+      "action",
+      actionId,
+    );
+  }
+
+  graphemeToSpokenForm(grapheme: string) {
+    return this.spokenFormGenerator.getSpokenFormForSingleTerm(
+      "grapheme",
+      grapheme,
+    );
   }
 
   getCustomRegexScopeTypes() {

packages/cursorless-engine/src/generateSpokenForm/generateSpokenForm.ts

@@ -5,24 +5,26 @@ import {
   InsertionMode,
   PartialTargetDescriptor,
   ScopeType,
+  SpokenForm,
+  SpokenFormMapKeyTypes,
+  SpokenFormType,
   camelCaseToAllDown,
 } from "@cursorless/common";
+import { SpokenFormMap } from "../spokenForms/SpokenFormMap";
 import { NoSpokenFormError } from "./NoSpokenFormError";
+import { SpokenFormComponent } from "./SpokenFormComponent";
 import { connectives } from "./defaultSpokenForms/connectives";
 import { surroundingPairDelimitersToSpokenForm } from "./defaultSpokenForms/modifiers";
 import {
   insertionSnippetToSpokenForm,
   wrapperSnippetToSpokenForm,
 } from "./defaultSpokenForms/snippets";
 import { getRangeConnective } from "./getRangeConnective";
-import { SpokenFormMap } from "../spokenForms/SpokenFormMap";
-import { PrimitiveTargetSpokenFormGenerator } from "./primitiveTargetToSpokenForm";
 import {
   SpokenFormComponentMap,
   getSpokenFormComponentMap,
 } from "./getSpokenFormComponentMap";
-import { SpokenFormComponent } from "./SpokenFormComponent";
-import { SpokenForm } from "@cursorless/common";
+import { PrimitiveTargetSpokenFormGenerator } from "./primitiveTargetToSpokenForm";
 
 export class SpokenFormGenerator {
   private primitiveGenerator: PrimitiveTargetSpokenFormGenerator;
@@ -36,6 +38,23 @@ export class SpokenFormGenerator {
     );
   }
 
+  getSpokenFormForSingleTerm<T extends SpokenFormType>(
+    type: T,
+    id: SpokenFormMapKeyTypes[T],
+  ): SpokenForm {
+    return this.componentsToSpokenForm(() => {
+      const value = this.spokenFormMap[type][
+        id as unknown as keyof SpokenFormComponentMap[T]
+      ] as SpokenFormComponent;
+
+      if (value == null) {
+        throw new NoSpokenFormError(`${type} with id ${id}`);
+      }
+
+      return value;
+    });
+  }
+
   /**
    * Given a command, generates its spoken form.
    * @param command The command to generate a spoken form for

packages/cursorless-engine/src/index.ts

@@ -2,11 +2,12 @@ export * from "./api/CursorlessEngineApi";
 export * from "./CommandHistory";
 export * from "./CommandHistoryAnalyzer";
 export * from "./CommandRunner";
+export * from "./core/commandVersionUpgrades/canonicalizeAndValidateCommand";
 export * from "./core/mergeSnippets";
 export * from "./core/Snippets";
 export * from "./core/StoredTargets";
-export * from "./core/StoredTargets";
 export * from "./cursorlessEngine";
+export * from "./customCommandGrammar/parseCommand";
 export * from "./generateSpokenForm/defaultSpokenForms/surroundingPairsDelimiters";
 export * from "./generateSpokenForm/generateSpokenForm";
 export * from "./singletons/ide.singleton";

packages/cursorless-engine/src/scopeProviders/ScopeRangeWatcher.ts

@@ -9,18 +9,17 @@ import {
 } from "@cursorless/common";
 import { pull } from "lodash-es";
 
-import { Debouncer } from "../core/Debouncer";
 import { LanguageDefinitions } from "../languages/LanguageDefinitions";
 import { ide } from "../singletons/ide.singleton";
 import { ScopeRangeProvider } from "./ScopeRangeProvider";
+import { DecorationDebouncer } from "../util/DecorationDebouncer";
 
 /**
  * Watches for changes to the scope ranges of visible editors and notifies
  * listeners when they change.
  */
 export class ScopeRangeWatcher {
   private disposables: Disposable[] = [];
-  private debouncer = new Debouncer(() => this.onChange());
   private listeners: (() => void)[] = [];
 
   constructor(
@@ -32,20 +31,24 @@ export class ScopeRangeWatcher {
     this.onDidChangeIterationScopeRanges =
       this.onDidChangeIterationScopeRanges.bind(this);
 
+    const debouncer = new DecorationDebouncer(ide().configuration, () =>
+      this.onChange(),
+    );
+
     this.disposables.push(
       // An Event which fires when the array of visible editors has changed.
-      ide().onDidChangeVisibleTextEditors(this.debouncer.run),
+      ide().onDidChangeVisibleTextEditors(debouncer.run),
       // An event that fires when a text document opens
-      ide().onDidOpenTextDocument(this.debouncer.run),
+      ide().onDidOpenTextDocument(debouncer.run),
       // An Event that fires when a text document closes
-      ide().onDidCloseTextDocument(this.debouncer.run),
+      ide().onDidCloseTextDocument(debouncer.run),
       // An event that is emitted when a text document is changed. This usually
       // happens when the contents changes but also when other things like the
       // dirty-state changes.
-      ide().onDidChangeTextDocument(this.debouncer.run),
-      ide().onDidChangeTextEditorVisibleRanges(this.debouncer.run),
+      ide().onDidChangeTextDocument(debouncer.run),
+      ide().onDidChangeTextEditorVisibleRanges(debouncer.run),
       languageDefinitions.onDidChangeDefinition(this.onChange),
-      this.debouncer,
+      debouncer,
     );
   }