commands: add support for tree-sitter textobjects

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "search.exclude": {
+    ".direnv": true,
     "out": true
   },
 

src/commands/load-all.build.ts

@@ -135,7 +135,11 @@ function determineFunctionExpression(f: Builder.ParsedFunction) {
       break;
 
     case "treeSitter":
-      givenParameters.push("_.extension.treeSitterOrThrow()");
+      if (type === "TreeSitter | undefined") {
+        givenParameters.push("_.extension.treeSitter");
+      } else {
+        givenParameters.push("_.extension.treeSitterOrThrow()");
+      }
       break;
 
     case "documentTree":

src/commands/seek.ts

@@ -286,6 +286,8 @@ export async function object(
   inner: Argument<boolean> = false,
   where?: Argument<"start" | "end">,
   shift = Shift.Select,
+
+  treeSitter?: TreeSitter,
 ) {
   const input = await inputOr(() => prompt({
     prompt: "Object description",
@@ -492,6 +494,70 @@ export async function object(
     return Selections.set(newSelections);
   }
 
+  // Helix text objects:
+  //   https://github.com/helix-editor/helix/blob/master/book/src/guides/textobject.md#L1
+  if (match = /^\(\?#textobject=(\w+)\)$/.exec(input)) {
+    if (treeSitter === undefined) {
+      throw new Error("tree-sitter is not available");
+    }
+
+    const query = await treeSitter.textObjectQueryFor(_.document);
+
+    if (query === undefined) {
+      throw new Error("no textobject query available for current document");
+    }
+
+    // Languages with queries available are a subset of supported languages, so
+    // given that we have a `query` `withDocumentTree()` will not fail.
+    const newSelections = await treeSitter.withDocumentTree(_.document, async (documentTree) => {
+      const textObjectName = match![1] + (inner ? ".inside" : ".around");
+
+      if (!query.captureNames.includes(textObjectName)) {
+        const existingValues = query.captureNames.map((name) =>
+          `"${name.replace(".inside", "").replace(".around", "")}"`
+        ).join(", ");
+
+        throw new Error(
+          `unknown textobject ${JSON.stringify(textObjectName)}, valid values are ${existingValues}`,
+        );
+      }
+
+      // TODO(71): add helpers for checking if a VS Code Position is within a Tree
+      //   Sitter range without creating temporary objects
+      const captures = query.captures(documentTree.rootNode)
+        .filter((capture) => capture.name === textObjectName)
+        .map(({ node }) => [node, treeSitter.toRange(node)] as const);
+
+      return Selections.mapByIndex((_i, selection) => {
+        const active = selection.active;
+
+        let smallestNode: SyntaxNode | undefined;
+        let smallestNodeLength: number = Number.MAX_SAFE_INTEGER;
+
+        for (const [node, nodeRange] of captures) {
+          if (!nodeRange.contains(active)) {
+            continue;
+          }
+
+          const nodeLength = node.endIndex - node.startIndex;
+
+          if (nodeLength < smallestNodeLength && !nodeRange.isEqual(selection)) {
+            smallestNode = node;
+          }
+        }
+
+        return smallestNode === undefined
+          ? selection
+          : Selections.fromStartEnd(
+              treeSitter.toPosition(smallestNode.startPosition),
+              treeSitter.toPosition(smallestNode.endPosition),
+              Selections.isStrictlyReversed(selection, _));
+      });
+    });
+
+    return Selections.set(newSelections);
+  }
+
   throw new Error("unknown object " + JSON.stringify(input));
 }
 

src/state/extension.ts

@@ -105,6 +105,10 @@ export class Extension implements vscode.Disposable {
     }
   }
 
+  public get treeSitter(): TreeSitter | undefined {
+    return this._treeSitter;
+  }
+
   public treeSitterOrThrow(): TreeSitter {
     if (this._treeSitter === undefined) {
       throw new Error("TreeSitter is not available");

src/utils/tree-sitter-api.d.ts

@@ -127,6 +127,16 @@ export declare const withQuerySync: <T>(language: HasLanguage, source: string, k
 export declare function using<T, Args extends {
     delete(): void;
 }[]>(...args: [...Args, (...args: Args) => T]): T;
+/**
+ * Returns the built-in {@link Query} for textobjects of the given language, or
+ * `undefined` if there is no such built-in query.
+ *
+ * This function automatically memoizes its results; callers should neither
+ * cache nor {@link Query.delete delete} the returned query.
+ *
+ * @see https://docs.helix-editor.com/guides/textobject.html
+ */
+export declare function textObjectQueryFor(input: HasLanguage): Promise<Omit<Query, "delete"> | undefined>;
 /**
  * A Tree Sitter point with UTF-16-based offsets.
  *