Added explicit mark (#1578)

Fixes #1577

## Checklist

- [x] 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

---------

Co-authored-by: Pokey Rule <[email protected]>
Co-authored-by: Phil Cohen <[email protected]>

Author: 3 people

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

@@ -43,14 +43,37 @@ export interface RangeMark {
   excludeActive?: boolean;
 }
 
+interface SimplePosition {
+  readonly line: number;
+  readonly character: number;
+}
+
+interface SimpleRange {
+  readonly start: SimplePosition;
+  readonly end: SimplePosition;
+}
+
+/**
+ * Used to explicitly provide a range for use as a mark. Today, this mark type
+ * is only used as a hack to enable us to support allowing other editors to
+ * maintain their own hat map when using the Cursorless "sidecar"; see
+ * https://github.com/cursorless-everywhere/notes for more information.
+ */
+export interface ExplicitMark {
+  type: "explicit";
+  editorId: string;
+  range: SimpleRange;
+}
+
 export type PartialMark =
   | CursorMark
   | ThatMark
   | SourceMark
   | DecoratedSymbolMark
   | NothingMark
   | LineNumberMark
-  | RangeMark;
+  | RangeMark
+  | ExplicitMark;
 
 export type SimpleSurroundingPairName =
   | "angleBrackets"

packages/cursorless-engine/src/processTargets/MarkStageFactoryImpl.ts

@@ -1,15 +1,16 @@
 import { ReadOnlyHatMap } from "@cursorless/common";
+import { TargetPipelineRunner } from ".";
 import { StoredTargetMap } from "..";
+import { Mark } from "../typings/TargetDescriptor";
 import { MarkStageFactory } from "./MarkStageFactory";
 import { MarkStage } from "./PipelineStages.types";
 import CursorStage from "./marks/CursorStage";
 import DecoratedSymbolStage from "./marks/DecoratedSymbolStage";
+import ExplicitMarkStage from "./marks/ExplicitMarkStage";
 import LineNumberStage from "./marks/LineNumberStage";
 import NothingStage from "./marks/NothingStage";
 import RangeMarkStage from "./marks/RangeMarkStage";
 import { StoredTargetStage } from "./marks/StoredTargetStage";
-import { Mark } from "../typings/TargetDescriptor";
-import { TargetPipelineRunner } from ".";
 import { TargetMarkStage } from "./marks/TargetMarkStage";
 
 export class MarkStageFactoryImpl implements MarkStageFactory {
@@ -43,6 +44,8 @@ export class MarkStageFactoryImpl implements MarkStageFactory {
         return new NothingStage(mark);
       case "target":
         return new TargetMarkStage(this.targetPipelineRunner, mark);
+      case "explicit":
+        return new ExplicitMarkStage(mark);
     }
   }
 }

packages/cursorless-engine/src/processTargets/marks/ExplicitMarkStage.ts

@@ -0,0 +1,38 @@
+import { ExplicitMark, Range } from "@cursorless/common";
+import { Target } from "../../typings/target.types";
+import { MarkStage } from "../PipelineStages.types";
+import { UntypedTarget } from "../targets";
+import { ide } from "../../singletons/ide.singleton";
+
+export default class implements MarkStage {
+  constructor(private mark: ExplicitMark) {}
+
+  run(): Target[] {
+    const {
+      editorId,
+      range: { start, end },
+    } = this.mark;
+
+    const editor = ide().visibleTextEditors.find((e) => e.id === editorId);
+
+    if (editor == null) {
+      throw new Error(`Couldn't find editor '${editorId}'`);
+    }
+
+    const contentRange = new Range(
+      start.line,
+      start.character,
+      end.line,
+      end.character,
+    );
+
+    return [
+      new UntypedTarget({
+        editor,
+        contentRange,
+        isReversed: false,
+        hasExplicitRange: false,
+      }),
+    ];
+  }
+}

packages/cursorless-vscode-e2e/src/suite/explicitMark.vscode.test.ts

@@ -0,0 +1,43 @@
+import {
+  getCursorlessApi,
+  openNewEditor,
+  runCursorlessCommand,
+} from "@cursorless/vscode-common";
+import * as assert from "assert";
+import { Selection } from "vscode";
+import { endToEndTestSetup } from "../endToEndTestSetup";
+
+suite("Explicit mark", async function () {
+  endToEndTestSetup(this);
+
+  test("Clear explicit mark", explicitMark);
+});
+
+async function explicitMark() {
+  const { ide } = (await getCursorlessApi()).testHelpers!;
+  const editor = await openNewEditor("foo bar baz");
+  const editorId = ide.visibleTextEditors[0].id;
+
+  await runCursorlessCommand({
+    version: 6,
+    usePrePhraseSnapshot: false,
+    action: {
+      name: "clearAndSetSelection",
+      target: {
+        type: "primitive",
+        mark: {
+          type: "explicit",
+          editorId,
+          range: {
+            start: { line: 0, character: 4 },
+            end: { line: 0, character: 7 },
+          },
+        },
+      },
+    },
+  });
+
+  assert.equal(editor.document.getText(), "foo  baz");
+  assert.equal(editor.selections.length, 1);
+  assert.ok(editor.selections[0].isEqual(new Selection(0, 4, 0, 4)));
+}