Destinations as first-class objects

packages/common/src/index.ts

@@ -65,13 +65,17 @@ export * from "./util/CompositeKeyMap";
 export * from "./ide/normalized/NormalizedIDE";
 export * from "./types/command/command.types";
 export * from "./types/command/PartialTargetDescriptor.types";
-export * from "./types/command/ActionCommand";
+export * from "./types/command/DestinationDescriptor.types";
+export * from "./types/command/ActionDescriptor";
 export * from "./types/command/legacy/CommandV0V1.types";
 export * from "./types/command/legacy/CommandV2.types";
 export * from "./types/command/legacy/CommandV3.types";
 export * from "./types/command/legacy/CommandV4.types";
 export * from "./types/command/legacy/targetDescriptorV2.types";
-export * from "./types/command/CommandV5.types";
+export * from "./types/command/legacy/ActionCommandV5";
+export * from "./types/command/legacy/CommandV5.types";
+export * from "./types/command/legacy/PartialTargetDescriptorV5.types";
+export * from "./types/command/CommandV6.types";
 export * from "./types/command/legacy/PartialTargetDescriptorV3.types";
 export * from "./types/command/legacy/PartialTargetDescriptorV4.types";
 export * from "./types/CommandServerApi";

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

@@ -0,0 +1,228 @@
+import {
+  PartialTargetDescriptor,
+  ScopeType,
+} from "./PartialTargetDescriptor.types";
+import { DestinationDescriptor } from "./DestinationDescriptor.types";
+
+/**
+ * A simple action takes only a single target and no other arguments.
+ */
+const simpleActionNames = [
+  "clearAndSetSelection",
+  "copyToClipboard",
+  "cutToClipboard",
+  "deselect",
+  "editNewLineAfter",
+  "editNewLineBefore",
+  "experimental.setInstanceReference",
+  "extractVariable",
+  "findInWorkspace",
+  "foldRegion",
+  "followLink",
+  "indentLine",
+  "insertCopyAfter",
+  "insertCopyBefore",
+  "insertEmptyLineAfter",
+  "insertEmptyLineBefore",
+  "insertEmptyLinesAround",
+  "outdentLine",
+  "randomizeTargets",
+  "remove",
+  "rename",
+  "revealDefinition",
+  "revealTypeDefinition",
+  "reverseTargets",
+  "scrollToBottom",
+  "scrollToCenter",
+  "scrollToTop",
+  "setSelection",
+  "setSelectionAfter",
+  "setSelectionBefore",
+  "showDebugHover",
+  "showHover",
+  "showQuickFix",
+  "showReferences",
+  "sortTargets",
+  "toggleLineBreakpoint",
+  "toggleLineComment",
+  "unfoldRegion",
+] as const;
+
+const complexActionNames = [
+  "callAsFunction",
+  "editNew",
+  "executeCommand",
+  "generateSnippet",
+  "getText",
+  "highlight",
+  "insertSnippet",
+  "moveToTarget",
+  "pasteFromClipboard",
+  "replace",
+  "replaceWithTarget",
+  "rewrapWithPairedDelimiter",
+  "swapTargets",
+  "wrapWithPairedDelimiter",
+  "wrapWithSnippet",
+] as const;
+
+export const actionNames = [
+  ...simpleActionNames,
+  ...complexActionNames,
+] as const;
+
+export type SimpleActionName = (typeof simpleActionNames)[number];
+export type ActionType = (typeof actionNames)[number];
+
+/**
+ * A simple action takes only a single target and no other arguments.
+ */
+export interface SimpleActionDescriptor {
+  name: SimpleActionName;
+  target: PartialTargetDescriptor;
+}
+
+export interface BringMoveActionDescriptor {
+  name: "replaceWithTarget" | "moveToTarget";
+  source: PartialTargetDescriptor;
+  destination: DestinationDescriptor;
+}
+
+export interface CallActionDescriptor {
+  name: "callAsFunction";
+
+  /**
+   * The target to use as the function to be called.
+   */
+  callee: PartialTargetDescriptor;
+
+  /**
+   * The target to wrap in a function call.
+   */
+  argument: PartialTargetDescriptor;
+}
+
+export interface SwapActionDescriptor {
+  name: "swapTargets";
+  target1: PartialTargetDescriptor;
+  target2: PartialTargetDescriptor;
+}
+
+export interface WrapWithPairedDelimiterActionDescriptor {
+  name: "wrapWithPairedDelimiter" | "rewrapWithPairedDelimiter";
+  left: string;
+  right: string;
+  target: PartialTargetDescriptor;
+}
+
+export interface PasteActionDescriptor {
+  name: "pasteFromClipboard";
+  destination: DestinationDescriptor;
+}
+
+export interface GenerateSnippetActionDescriptor {
+  name: "generateSnippet";
+  snippetName?: string;
+  target: PartialTargetDescriptor;
+}
+
+interface NamedInsertSnippetArg {
+  type: "named";
+  name: string;
+  substitutions?: Record<string, string>;
+}
+interface CustomInsertSnippetArg {
+  type: "custom";
+  body: string;
+  scopeType?: ScopeType;
+  substitutions?: Record<string, string>;
+}
+export type InsertSnippetArg = NamedInsertSnippetArg | CustomInsertSnippetArg;
+
+export interface InsertSnippetActionDescriptor {
+  name: "insertSnippet";
+  snippetDescription: InsertSnippetArg;
+  destination: DestinationDescriptor;
+}
+
+interface NamedWrapWithSnippetArg {
+  type: "named";
+  name: string;
+  variableName: string;
+}
+interface CustomWrapWithSnippetArg {
+  type: "custom";
+  body: string;
+  variableName?: string;
+  scopeType?: ScopeType;
+}
+export type WrapWithSnippetArg =
+  | NamedWrapWithSnippetArg
+  | CustomWrapWithSnippetArg;
+
+export interface WrapWithSnippetActionDescriptor {
+  name: "wrapWithSnippet";
+  snippetDescription: WrapWithSnippetArg;
+  target: PartialTargetDescriptor;
+}
+
+export interface ExecuteCommandOptions {
+  commandArgs?: any[];
+  ensureSingleEditor?: boolean;
+  ensureSingleTarget?: boolean;
+  restoreSelection?: boolean;
+  showDecorations?: boolean;
+}
+
+export interface ExecuteCommandActionDescriptor {
+  name: "executeCommand";
+  commandId: string;
+  options?: ExecuteCommandOptions;
+  target: PartialTargetDescriptor;
+}
+
+export type ReplaceWith = string[] | { start: number };
+
+export interface ReplaceActionDescriptor {
+  name: "replace";
+  replaceWith: ReplaceWith;
+  destination: DestinationDescriptor;
+}
+
+export interface HighlightActionDescriptor {
+  name: "highlight";
+  highlightId?: string;
+  target: PartialTargetDescriptor;
+}
+
+export interface EditNewActionDescriptor {
+  name: "editNew";
+  destination: DestinationDescriptor;
+}
+
+export interface GetTextActionOptions {
+  showDecorations?: boolean;
+  ensureSingleTarget?: boolean;
+}
+
+export interface GetTextActionDescriptor {
+  name: "getText";
+  options?: GetTextActionOptions;
+  target: PartialTargetDescriptor;
+}
+
+export type ActionDescriptor =
+  | SimpleActionDescriptor
+  | BringMoveActionDescriptor
+  | SwapActionDescriptor
+  | CallActionDescriptor
+  | PasteActionDescriptor
+  | ExecuteCommandActionDescriptor
+  | ReplaceActionDescriptor
+  | HighlightActionDescriptor
+  | GenerateSnippetActionDescriptor
+  | InsertSnippetActionDescriptor
+  | WrapWithSnippetActionDescriptor
+  | WrapWithPairedDelimiterActionDescriptor
+  | EditNewActionDescriptor
+  | GetTextActionDescriptor;

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

@@ -0,0 +1,27 @@
+import type { ActionDescriptor } from "./ActionDescriptor";
+
+export interface CommandV6 {
+  /**
+   * The version number of the command API
+   */
+  version: 6;
+
+  /**
+   * The spoken form of the command if issued from a voice command system
+   */
+  spokenForm?: string;
+
+  /**
+   * If the command is issued from a voice command system, this boolean indicates
+   * whether we should use the pre phrase snapshot. Only set this to true if the
+   * voice command system issues a pre phrase signal at the start of every
+   * phrase.
+   */
+  usePrePhraseSnapshot: boolean;
+
+  /**
+   * The action to perform. This field contains everything necessary to actually
+   * perform the action. The other fields are just metadata.
+   */
+  action: ActionDescriptor;
+}

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

@@ -0,0 +1,55 @@
+import {
+  PartialListTargetDescriptor,
+  PartialPrimitiveTargetDescriptor,
+  PartialRangeTargetDescriptor,
+} from "./PartialTargetDescriptor.types";
+
+/**
+ * The insertion mode to use when inserting relative to a target.
+ * - `before` inserts before the target.  Depending on the target, a delimiter
+ *   may be inserted after the inserted text.
+ * - `after` inserts after the target.  Depending on the target, a delimiter may
+ *   be inserted before the inserted text.
+ * - `to` replaces the target.  However, this insertion mode may also be used
+ *   when the target is really only a pseudo-target.  For example, you could say
+ *   `"bring type air to bat"` even if `bat` doesn't already have a type.  In
+ *   that case, `"take type bat"` wouldn't work, so `"type bat"` is really just
+ *   a pseudo-target in that situation.
+ */
+export type InsertionMode = "before" | "after" | "to";
+
+export interface PrimitiveDestinationDescriptor {
+  type: "primitive";
+
+  /**
+   * The insertion mode to use when inserting relative to {@link target}.
+   */
+  insertionMode: InsertionMode;
+
+  target:
+    | PartialPrimitiveTargetDescriptor
+    | PartialRangeTargetDescriptor
+    | PartialListTargetDescriptor;
+}
+
+/**
+ * A list of destinations.  This is used when the user uses more than one insertion mode
+ * in a single command.  For example, `"bring air after bat and before cap"`.
+ */
+export interface ListDestinationDescriptor {
+  type: "list";
+  destinations: PrimitiveDestinationDescriptor[];
+}
+
+/**
+ * An implicit destination.  This is used for e.g. `"bring air"` (note the user
+ * doesn't explicitly specify the destination), or `"snip funk"`.
+ */
+export interface ImplicitDestinationDescriptor {
+  type: "implicit";
+}
+
+export type DestinationDescriptor =
+  | ListDestinationDescriptor
+  | PrimitiveDestinationDescriptor
+  | ImplicitDestinationDescriptor;

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

@@ -268,21 +268,21 @@ export interface InferPreviousMarkModifier {
   type: "inferPreviousMark";
 }
 
-export type TargetPosition = "before" | "after" | "start" | "end";
+export interface StartOfModifier {
+  type: "startOf";
+}
 
-export interface PositionModifier {
-  type: "position";
-  position: TargetPosition;
+export interface EndOfModifier {
+  type: "endOf";
 }
 
-export interface PartialPrimitiveTargetDescriptor {
-  type: "primitive";
-  mark?: PartialMark;
+export interface HeadModifier {
+  type: "extendThroughStartOf";
   modifiers?: Modifier[];
 }
 
-export interface HeadTailModifier {
-  type: "extendThroughStartOf" | "extendThroughEndOf";
+export interface TailModifier {
+  type: "extendThroughEndOf";
   modifiers?: Modifier[];
 }
 
@@ -326,14 +326,16 @@ export interface RangeModifier {
 }
 
 export type Modifier =
-  | PositionModifier
+  | StartOfModifier
+  | EndOfModifier
   | InteriorOnlyModifier
   | ExcludeInteriorModifier
   | ContainingScopeModifier
   | EveryScopeModifier
   | OrdinalScopeModifier
   | RelativeScopeModifier
-  | HeadTailModifier
+  | HeadModifier
+  | TailModifier
   | LeadingModifier
   | TrailingModifier
   | RawSelectionModifier
@@ -348,6 +350,12 @@ export type Modifier =
 // vertical puts a selection on each line vertically between the two targets
 export type PartialRangeType = "continuous" | "vertical";
 
+export interface PartialPrimitiveTargetDescriptor {
+  type: "primitive";
+  mark?: PartialMark;
+  modifiers?: Modifier[];
+}
+
 export interface PartialRangeTargetDescriptor {
   type: "range";
   anchor: PartialPrimitiveTargetDescriptor | ImplicitTargetDescriptor;