replace treesitter #start-position with .startof (#1682)

This particular query pattern is going to be very common.
It's worth having syntactic sugar for.
In particular, this reduces the level of indentation
required to express that a node's associated scope
(iteration, trailing, leading, etc.)
should start or end at the start or end of a different node.

While we're here, make a related error message more helpful.



## 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]>

Author: josharian

packages/cursorless-engine/src/languages/TreeSitterQuery/TreeSitterQuery.ts

@@ -8,6 +8,7 @@ import { parsePredicates } from "./parsePredicates";
 import { predicateToString } from "./predicateToString";
 import { groupBy, uniq } from "lodash";
 import { checkCaptureStartEnd } from "./checkCaptureStartEnd";
+import { rewriteStartOfEndOf } from "./rewriteStartOfEndOf";
 
 /**
  * Wrapper around a tree-sitter query that provides a more convenient API, and
@@ -95,6 +96,7 @@ export class TreeSitterQuery {
         const captures: QueryCapture[] = Object.entries(
           groupBy(match.captures, ({ name }) => normalizeCaptureName(name)),
         ).map(([name, captures]) => {
+          captures = rewriteStartOfEndOf(captures);
           const capturesAreValid = checkCaptureStartEnd(
             captures,
             ide().messages,
@@ -123,7 +125,7 @@ export class TreeSitterQuery {
 }
 
 function normalizeCaptureName(name: string): string {
-  return name.replace(/\.(start|end)$/, "");
+  return name.replace(/(\.(start|end))?(\.(startOf|endOf))?$/, "");
 }
 
 function positionToPoint(start: Position): Point {

packages/cursorless-engine/src/languages/TreeSitterQuery/checkCaptureStartEnd.ts

@@ -68,7 +68,9 @@ export function checkCaptureStartEnd(
     showError(
       messages,
       "TreeSitterQuery.checkCaptures.duplicate",
-      `A capture with the same name may only appear once in a single pattern: ${captures}`,
+      `A capture with the same name may only appear once in a single pattern: ${captures.map(
+        ({ name }) => name,
+      )}`,
     );
     shownError = true;
   }

packages/cursorless-engine/src/languages/TreeSitterQuery/queryPredicateOperators.ts

@@ -1,4 +1,3 @@
-import { Range } from "@cursorless/common";
 import z from "zod";
 import { makeRangeFromPositions } from "../../util/nodeSelectors";
 import { MutableQueryCapture } from "./QueryCapture";
@@ -46,40 +45,6 @@ class IsNthChild extends QueryPredicateOperator<IsNthChild> {
   }
 }
 
-/**
- * A predicate operator that modifies the range of the match to be a zero-width
- * range at the start of the node.  For example, `(#start-position! @foo)` will
- * modify the range of the `@foo` capture to be a zero-width range at the start
- * of the `@foo` node.
- */
-class StartPosition extends QueryPredicateOperator<StartPosition> {
-  name = "start-position!" as const;
-  schema = z.tuple([q.node]);
-
-  run(nodeInfo: MutableQueryCapture) {
-    nodeInfo.range = new Range(nodeInfo.range.start, nodeInfo.range.start);
-
-    return true;
-  }
-}
-
-/**
- * A predicate operator that modifies the range of the match to be a zero-width
- * range at the end of the node.  For example, `(#end-position! @foo)` will
- * modify the range of the `@foo` capture to be a zero-width range at the end of
- * the `@foo` node.
- */
-class EndPosition extends QueryPredicateOperator<EndPosition> {
-  name = "end-position!" as const;
-  schema = z.tuple([q.node]);
-
-  run(nodeInfo: MutableQueryCapture) {
-    nodeInfo.range = new Range(nodeInfo.range.end, nodeInfo.range.end);
-
-    return true;
-  }
-}
-
 class ChildRange extends QueryPredicateOperator<ChildRange> {
   name = "child-range!" as const;
   schema = z.union([
@@ -131,8 +96,6 @@ export const queryPredicateOperators = [
   new NotType(),
   new NotParentType(),
   new IsNthChild(),
-  new StartPosition(),
-  new EndPosition(),
   new ChildRange(),
   new AllowMultiple(),
 ];

packages/cursorless-engine/src/languages/TreeSitterQuery/rewriteStartOfEndOf.test.ts

@@ -0,0 +1,73 @@
+import { Range } from "@cursorless/common";
+import { MutableQueryCapture } from "./QueryCapture";
+import { SyntaxNode } from "web-tree-sitter";
+import { rewriteStartOfEndOf } from "./rewriteStartOfEndOf";
+import assert = require("assert");
+
+type NameRange = Pick<MutableQueryCapture, "name" | "range">;
+
+interface TestCase {
+  name: string;
+  captures: NameRange[];
+  expected: NameRange[];
+}
+
+const testCases: TestCase[] = [
+  {
+    name: "should rewrite startOf to start of range",
+    captures: [
+      { name: "@value.iteration.start.startOf", range: new Range(1, 2, 1, 3) },
+      { name: "@collectionKey.startOf", range: new Range(1, 2, 1, 3) },
+    ],
+    expected: [
+      { name: "@value.iteration.start", range: new Range(1, 2, 1, 2) },
+      { name: "@collectionKey", range: new Range(1, 2, 1, 2) },
+    ],
+  },
+
+  {
+    name: "should rewrite endOf to start of range",
+    captures: [
+      { name: "@value.iteration.start.endOf", range: new Range(1, 2, 1, 3) },
+      { name: "@collectionKey.endOf", range: new Range(1, 2, 1, 3) },
+    ],
+    expected: [
+      { name: "@value.iteration.start", range: new Range(1, 3, 1, 3) },
+      { name: "@collectionKey", range: new Range(1, 3, 1, 3) },
+    ],
+  },
+
+  {
+    name: "should leave other captures alone",
+    captures: [
+      { name: "@value.iteration.start", range: new Range(1, 2, 1, 3) },
+      { name: "@collectionKey", range: new Range(1, 2, 1, 3) },
+    ],
+    expected: [
+      { name: "@value.iteration.start", range: new Range(1, 2, 1, 3) },
+      { name: "@collectionKey", range: new Range(1, 2, 1, 3) },
+    ],
+  },
+];
+
+suite("rewriteStartOfEndOf", () => {
+  for (const testCase of testCases) {
+    test(testCase.name, () => {
+      const actual = rewriteStartOfEndOf(
+        testCase.captures.map((capture) => ({
+          ...capture,
+          allowMultiple: false,
+          node: null as unknown as SyntaxNode,
+        })),
+      );
+      assert.deepStrictEqual(
+        actual,
+        testCase.expected.map((capture) => ({
+          ...capture,
+          allowMultiple: false,
+          node: null as unknown as SyntaxNode,
+        })),
+      );
+    });
+  }
+});

packages/cursorless-engine/src/languages/TreeSitterQuery/rewriteStartOfEndOf.ts

@@ -0,0 +1,32 @@
+import { MutableQueryCapture } from "./QueryCapture";
+
+/**
+ * Modifies captures by applying any `.startOf` or `.endOf` suffixes. For
+ * example, if we have a capture `@value.startOf`, we would rename it to
+ * `@value` and adjust the range to be the start of the original range.
+ *
+ * @param captures A list of captures
+ * @returns rewritten captures, with .startOf and .endOf removed
+ */
+export function rewriteStartOfEndOf(
+  captures: MutableQueryCapture[],
+): MutableQueryCapture[] {
+  return captures.map((capture) => {
+    // Remove trailing .startOf and .endOf, adjusting ranges.
+    if (capture.name.endsWith(".startOf")) {
+      return {
+        ...capture,
+        name: capture.name.replace(/\.startOf$/, ""),
+        range: capture.range.start.toEmptyRange(),
+      };
+    }
+    if (capture.name.endsWith(".endOf")) {
+      return {
+        ...capture,
+        name: capture.name.replace(/\.endOf$/, ""),
+        range: capture.range.end.toEmptyRange(),
+      };
+    }
+    return capture;
+  });
+}

queries/javascript.core.scm

@@ -97,15 +97,11 @@
 ;; Treat interior of all bodies as iteration scopes for `name`, eg
 ;;!! function foo() {   }
 ;;!                  ***
-(
-  (_
-    body: (_
-        .
-        "{" @name.iteration.start
-        "}" @name.iteration.end
-        .
-    )
+(_
+  body: (_
+      .
+      "{" @name.iteration.start.endOf
+      "}" @name.iteration.end.startOf
+      .
   )
-  (#end-position! @name.iteration.start)
-  (#start-position! @name.iteration.end)
 )

queries/javascript.jsx.scm

@@ -77,10 +77,7 @@
 ;;!! <>foo</>
 ;;!  {}    {}
 ;;!  --   ---
-(
-  (jsx_fragment
-    "<" @_.domain.start
-    ">" @name @_.domain.end
-  )
-  (#start-position! @name)
+(jsx_fragment
+  "<" @_.domain.start
+  ">" @name.startOf @_.domain.end
 )