More sophisticated custom spoken forms

Author: pokey

cursorless-talon/src/cursorless.py

@@ -14,4 +14,4 @@ def private_cursorless_show_settings_in_ide():
         """Show Cursorless-specific settings in ide"""
 
     def private_cursorless_show_sidebar():
-        """Show Cursorless sidebar"""
+        """Show Cursorless-specific settings in ide"""

packages/common/src/types/command/PartialTargetDescriptor.types.ts

@@ -175,6 +175,15 @@ export function isSimpleScopeType(
   return (simpleScopeTypeTypes as readonly string[]).includes(scopeType.type);
 }
 
+const SECRET_SCOPE_TYPES = [
+  "string",
+  "switchStatementSubject",
+] as const satisfies readonly SimpleScopeTypeType[];
+
+export function isSecretScopeType(scopeType: ScopeType): boolean {
+  return (SECRET_SCOPE_TYPES as readonly string[]).includes(scopeType.type);
+}
+
 export type SimpleScopeTypeType = (typeof simpleScopeTypeTypes)[number];
 
 export interface SimpleScopeType {

packages/cursorless-engine/src/CustomSpokenForms.ts

@@ -3,18 +3,25 @@ import {
   Disposer,
   FileSystem,
   Notifier,
+  showError,
 } from "@cursorless/common";
-import { homedir } from "os";
-import * as path from "path";
-import { getSpokenFormEntries } from "./scopeProviders/getSpokenFormEntries";
-import { SpokenFormMap } from "./SpokenFormMap";
-import { defaultSpokenFormMap } from "./DefaultSpokenFormMap";
-
-export const spokenFormsPath = path.join(
-  homedir(),
-  ".cursorless",
-  "spokenForms.json",
-);
+import { isEqual } from "lodash";
+import {
+  defaultSpokenFormInfo,
+  defaultSpokenFormMap,
+} from "./DefaultSpokenFormMap";
+import {
+  SpokenFormMap,
+  SpokenFormMapEntry,
+  SpokenFormType,
+} from "./SpokenFormMap";
+import {
+  SpokenFormEntry,
+  getSpokenFormEntries,
+  spokenFormsPath,
+} from "./scopeProviders/getSpokenFormEntries";
+import { ide } from "./singletons/ide.singleton";
+import { dirname } from "node:path";
 
 const ENTRY_TYPES = [
   "simpleScopeTypeType",
@@ -41,6 +48,15 @@ export class CustomSpokenForms implements SpokenFormMap {
   modifierExtra = defaultSpokenFormMap.modifierExtra;
 
   private isInitialized_ = false;
+  private needsInitialTalonUpdate_: boolean | undefined;
+
+  /**
+   * If `true`, indicates they need to update their Talon files to get the
+   * machinery used to share spoken forms from Talon to the VSCode extension.
+   */
+  get needsInitialTalonUpdate() {
+    return this.needsInitialTalonUpdate_;
+  }
 
   /**
    * Whether the custom spoken forms have been initialized. If `false`, the
@@ -53,7 +69,9 @@ export class CustomSpokenForms implements SpokenFormMap {
 
   constructor(fileSystem: FileSystem) {
     this.disposer.push(
-      fileSystem.watch(spokenFormsPath, () => this.updateSpokenFormMaps()),
+      fileSystem.watch(dirname(spokenFormsPath), () =>
+        this.updateSpokenFormMaps(),
+      ),
     );
 
     this.updateSpokenFormMaps();
@@ -67,7 +85,30 @@ export class CustomSpokenForms implements SpokenFormMap {
   onDidChangeCustomSpokenForms = this.notifier.registerListener;
 
   private async updateSpokenFormMaps(): Promise<void> {
-    const entries = await getSpokenFormEntries();
+    let entries: SpokenFormEntry[];
+    try {
+      entries = await getSpokenFormEntries();
+    } catch (err) {
+      if ((err as any)?.code === "ENOENT") {
+        // Handle case where spokenForms.json doesn't exist yet
+        console.log(
+          `Custom spoken forms file not found at ${spokenFormsPath}. Using default spoken forms.`,
+        );
+        this.needsInitialTalonUpdate_ = true;
+        this.notifier.notifyListeners();
+      } else {
+        console.error("Error loading custom spoken forms", err);
+        showError(
+          ide().messages,
+          "CustomSpokenForms.updateSpokenFormMaps",
+          `Error loading custom spoken forms: ${
+            (err as Error).message
+          }}}. Falling back to default spoken forms.`,
+        );
+      }
+
+      return;
+    }
 
     for (const entryType of ENTRY_TYPES) {
       // TODO: Handle case where we've added a new scope type but they haven't yet
@@ -76,10 +117,45 @@ export class CustomSpokenForms implements SpokenFormMap {
       // be able to speak it. We could just detect that there's no entry for it in
       // the spoken forms file, but that feels a bit brittle.
       // FIXME: How to avoid the type assertion?
-      this[entryType] = Object.fromEntries(
+      const entry = Object.fromEntries(
         entries
           .filter((entry) => entry.type === entryType)
           .map(({ id, spokenForms }) => [id, spokenForms]),
+      );
+
+      this[entryType] = Object.fromEntries(
+        Object.entries(defaultSpokenFormInfo[entryType]).map(
+          ([key, { defaultSpokenForms, isSecret }]): [
+            SpokenFormType,
+            SpokenFormMapEntry,
+          ] => {
+            const customSpokenForms = entry[key];
+            if (customSpokenForms != null) {
+              return [
+                key as SpokenFormType,
+                {
+                  defaultSpokenForms,
+                  spokenForms: customSpokenForms,
+                  requiresTalonUpdate: false,
+                  isCustom: isEqual(defaultSpokenForms, customSpokenForms),
+                  isSecret,
+                },
+              ];
+            } else {
+              return [
+                key as SpokenFormType,
+                {
+                  defaultSpokenForms,
+                  spokenForms: [],
+                  // If it's not a secret spoken form, then it's a new scope type
+                  requiresTalonUpdate: !isSecret,
+                  isCustom: false,
+                  isSecret,
+                },
+              ];
+            }
+          },
+        ),
       ) as any;
     }
 

packages/cursorless-engine/src/DefaultSpokenFormMap.ts

@@ -1,13 +1,17 @@
 import { mapValues } from "lodash";
-import { SpokenFormMap, SpokenFormMapKeyTypes } from "./SpokenFormMap";
+import {
+  SpokenFormMap,
+  SpokenFormMapEntry,
+  SpokenFormMapKeyTypes,
+} from "./SpokenFormMap";
 
-type DefaultSpokenFormMap = {
+type DefaultSpokenFormMapDefinition = {
   readonly [K in keyof SpokenFormMapKeyTypes]: Readonly<
-    Record<SpokenFormMapKeyTypes[K], string | null>
+    Record<SpokenFormMapKeyTypes[K], string | DefaultSpokenFormMapEntry>
   >;
 };
 
-const defaultSpokenFormMapCore: DefaultSpokenFormMap = {
+const defaultSpokenFormMapCore: DefaultSpokenFormMapDefinition = {
   pairedDelimiter: {
     curlyBrackets: "curly",
     angleBrackets: "diamond",
@@ -45,15 +49,14 @@ const defaultSpokenFormMapCore: DefaultSpokenFormMap = {
     name: "name",
     regularExpression: "regex",
     section: "section",
-    sectionLevelOne: "one section",
-    sectionLevelTwo: "two section",
-    sectionLevelThree: "three section",
-    sectionLevelFour: "four section",
-    sectionLevelFive: "five section",
-    sectionLevelSix: "six section",
+    sectionLevelOne: disabledByDefault("one section"),
+    sectionLevelTwo: disabledByDefault("two section"),
+    sectionLevelThree: disabledByDefault("three section"),
+    sectionLevelFour: disabledByDefault("four section"),
+    sectionLevelFive: disabledByDefault("five section"),
+    sectionLevelSix: disabledByDefault("six section"),
     selector: "selector",
     statement: "state",
-    string: "string",
     branch: "branch",
     type: "type",
     value: "value",
@@ -88,7 +91,8 @@ const defaultSpokenFormMapCore: DefaultSpokenFormMap = {
     url: "link",
     notebookCell: "cell",
 
-    switchStatementSubject: null,
+    string: secret("parse tree string"),
+    switchStatementSubject: secret("subject"),
   },
 
   surroundingPairForceDirection: {
@@ -124,10 +128,67 @@ const defaultSpokenFormMapCore: DefaultSpokenFormMap = {
   customRegex: {},
 };
 
-// TODO: Don't cast here; need to make our own mapValues with stronger typing
+function disabledByDefault(
+  ...spokenForms: string[]
+): DefaultSpokenFormMapEntry {
+  return {
+    defaultSpokenForms: spokenForms,
+    isDisabledByDefault: true,
+    isSecret: false,
+  };
+}
+
+function secret(...spokenForms: string[]): DefaultSpokenFormMapEntry {
+  return {
+    defaultSpokenForms: spokenForms,
+    isDisabledByDefault: true,
+    isSecret: true,
+  };
+}
+
+interface DefaultSpokenFormMapEntry {
+  defaultSpokenForms: string[];
+  isDisabledByDefault: boolean;
+  isSecret: boolean;
+}
+
+export type DefaultSpokenFormMap = {
+  readonly [K in keyof SpokenFormMapKeyTypes]: Readonly<
+    Record<SpokenFormMapKeyTypes[K], DefaultSpokenFormMapEntry>
+  >;
+};
+
+// FIXME: Don't cast here; need to make our own mapValues with stronger typing
 // using tricks from our object.d.ts
-export const defaultSpokenFormMap = mapValues(
+export const defaultSpokenFormInfo = mapValues(
   defaultSpokenFormMapCore,
   (entry) =>
-    mapValues(entry, (subEntry) => (subEntry == null ? [] : [subEntry])),
+    mapValues(entry, (subEntry) =>
+      typeof subEntry === "string"
+        ? {
+            defaultSpokenForms: [subEntry],
+            isDisabledByDefault: false,
+            isSecret: false,
+          }
+        : subEntry,
+    ),
+) as DefaultSpokenFormMap;
+
+// FIXME: Don't cast here; need to make our own mapValues with stronger typing
+// using tricks from our object.d.ts
+export const defaultSpokenFormMap = mapValues(defaultSpokenFormInfo, (entry) =>
+  mapValues(
+    entry,
+    ({
+      defaultSpokenForms,
+      isDisabledByDefault,
+      isSecret,
+    }): SpokenFormMapEntry => ({
+      spokenForms: isDisabledByDefault ? [] : defaultSpokenForms,
+      isCustom: false,
+      defaultSpokenForms,
+      requiresTalonUpdate: false,
+      isSecret,
+    }),
+  ),
 ) as SpokenFormMap;

packages/cursorless-engine/src/SpokenFormMap.ts

@@ -37,8 +37,16 @@ export interface SpokenFormMapKeyTypes {
 
 export type SpokenFormType = keyof SpokenFormMapKeyTypes;
 
+export interface SpokenFormMapEntry {
+  spokenForms: string[];
+  isCustom: boolean;
+  defaultSpokenForms: string[];
+  requiresTalonUpdate: boolean;
+  isSecret: boolean;
+}
+
 export type SpokenFormMap = {
   readonly [K in keyof SpokenFormMapKeyTypes]: Readonly<
-    Record<SpokenFormMapKeyTypes[K], string[]>
+    Record<SpokenFormMapKeyTypes[K], SpokenFormMapEntry>
   >;
 };

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

@@ -7,6 +7,7 @@ import { ScopeProvider } from "./ScopeProvider";
 export interface CursorlessEngine {
   commandApi: CommandApi;
   scopeProvider: ScopeProvider;
+  customSpokenFormGenerator: CustomSpokenFormGenerator;
   testCaseRecorder: TestCaseRecorder;
   storedTargets: StoredTargetMap;
   hatTokenMap: HatTokenMap;
@@ -15,6 +16,16 @@ export interface CursorlessEngine {
   runIntegrationTests: () => Promise<void>;
 }
 
+export interface CustomSpokenFormGenerator {
+  /**
+   * If `true`, indicates they need to update their Talon files to get the
+   * machinery used to share spoken forms from Talon to the VSCode extension.
+   */
+  readonly needsInitialTalonUpdate: boolean | undefined;
+
+  onDidChangeCustomSpokenForms: (listener: () => void) => void;
+}
+
 export interface CommandApi {
   /**
    * Runs a command.  This is the core of the Cursorless engine.

packages/cursorless-engine/src/cursorlessEngine.ts

@@ -13,7 +13,7 @@ import { HatTokenMapImpl } from "./core/HatTokenMapImpl";
 import { Snippets } from "./core/Snippets";
 import { ensureCommandShape } from "./core/commandVersionUpgrades/ensureCommandShape";
 import { RangeUpdater } from "./core/updateSelections/RangeUpdater";
-import { CustomSpokenFormGenerator } from "./generateSpokenForm/CustomSpokenFormGenerator";
+import { CustomSpokenFormGeneratorImpl } from "./generateSpokenForm/CustomSpokenFormGeneratorImpl";
 import { LanguageDefinitions } from "./languages/LanguageDefinitions";
 import { ModifierStageFactoryImpl } from "./processTargets/ModifierStageFactoryImpl";
 import { ScopeHandlerFactoryImpl } from "./processTargets/modifiers/scopeHandlers";
@@ -56,7 +56,7 @@ export function createCursorlessEngine(
 
   const languageDefinitions = new LanguageDefinitions(fileSystem, treeSitter);
 
-  const customSpokenFormGenerator = new CustomSpokenFormGenerator(fileSystem);
+  const customSpokenFormGenerator = new CustomSpokenFormGeneratorImpl(fileSystem);
 
   ide.disposeOnExit(rangeUpdater, languageDefinitions, hatTokenMap, debug);
 
@@ -97,6 +97,7 @@ export function createCursorlessEngine(
       storedTargets,
       customSpokenFormGenerator,
     ),
+    customSpokenFormGenerator,
     testCaseRecorder,
     storedTargets,
     hatTokenMap,
@@ -110,7 +111,7 @@ export function createCursorlessEngine(
 function createScopeProvider(
   languageDefinitions: LanguageDefinitions,
   storedTargets: StoredTargetMap,
-  customSpokenFormGenerator: CustomSpokenFormGenerator,
+  customSpokenFormGenerator: CustomSpokenFormGeneratorImpl,
 ): ScopeProvider {
   const scopeHandlerFactory = new ScopeHandlerFactoryImpl(languageDefinitions);
 

packages/cursorless-engine/src/generateSpokenForm/CustomSpokenFormGenerator.ts renamed to packages/cursorless-engine/src/generateSpokenForm/CustomSpokenFormGeneratorImpl.ts

@@ -6,9 +6,12 @@ import {
   ScopeType,
 } from "@cursorless/common";
 import { SpokenFormGenerator } from ".";
+import { CustomSpokenFormGenerator } from "..";
 import { CustomSpokenForms } from "../CustomSpokenForms";
 
-export class CustomSpokenFormGenerator {
+export class CustomSpokenFormGeneratorImpl
+  implements CustomSpokenFormGenerator
+{
   private customSpokenForms: CustomSpokenForms;
   private spokenFormGenerator: SpokenFormGenerator;
   private disposer = new Disposer();
@@ -41,5 +44,9 @@ export class CustomSpokenFormGenerator {
     return this.customSpokenForms.getCustomRegexScopeTypes();
   }
 
+  get needsInitialTalonUpdate() {
+    return this.customSpokenForms.needsInitialTalonUpdate;
+  }
+
   dispose = this.disposer.dispose;
 }