Text fragment scope (#2381)

Adds text fragment as a hidden scope. Allows us to use scope visualizer
and facet scope fixtures.

Additional languages can be done in a follow up. This just implements
the machinery and a single language as proof of concept.

![Screenshot 2024-06-01T15-42-38 - Visual Studio
Code](https://github.com/cursorless-dev/cursorless/assets/3511326/f2283790-d8dc-4c42-b5c0-4ca0783a22dc)



## 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 <755842+pokey@users.noreply.github.com>

Author: AndreasArvidsson

cursorless-talon/src/spoken_forms.py

@@ -130,6 +130,7 @@ def handle_new_values(csv_name: str, values: list[SpokenFormEntry]):
             extra_allowed_values=[
                 "private.fieldAccess",
                 "private.switchStatementSubject",
+                "textFragment",
             ],
             default_list_name="scope_type",
         ),

data/fixtures/scopes/c/comment.block.scope

@@ -0,0 +1,17 @@
+/*
+  the
+  comment
+*/
+---
+
+[Content] =
+[Removal] =
+[Domain] = 0:0-3:2
+  >--
+0| /*
+1|   the
+2|   comment
+3| */
+   --<
+
+[Insertion delimiter] = "\n"

data/fixtures/scopes/c/textFragment.comment.block.scope

@@ -0,0 +1,17 @@
+/*
+  the
+  comment
+*/
+---
+
+[Content] =
+[Removal] =
+[Domain] = 0:0-3:2
+  >--
+0| /*
+1|   the
+2|   comment
+3| */
+   --<
+
+[Insertion delimiter] = " "

data/fixtures/scopes/c/textFragment.comment.line.scope

@@ -0,0 +1,17 @@
+int a; // the comment
+---
+
+[Content] =
+[Domain] = 0:7-0:21
+         >--------------<
+0| int a; // the comment
+
+[Removal] = 0:6-0:21
+        >---------------<
+0| int a; // the comment
+
+[Leading delimiter] = 0:6-0:7
+        >-<
+0| int a; // the comment
+
+[Insertion delimiter] = " "

data/fixtures/scopes/c/textFragment.string.singleLine.scope

@@ -0,0 +1,10 @@
+char* a = "hello world";
+---
+
+[Content] =
+[Removal] =
+[Domain] = 0:11-0:22
+             >-----------<
+0| char* a = "hello world";
+
+[Insertion delimiter] = " "

packages/common/src/scopeSupportFacets/c.ts

@@ -10,8 +10,13 @@ const { supported, unsupported, notApplicable } = ScopeSupportFacetLevel;
 
 export const cScopeSupport: LanguageScopeSupportFacetMap = {
   ifStatement: supported,
+
   "comment.line": supported,
+  "comment.block": supported,
   "string.singleLine": supported,
+  "textFragment.comment.line": supported,
+  "textFragment.comment.block": supported,
+  "textFragment.string.singleLine": supported,
 
   class: supported,
   className: supported,

packages/common/src/scopeSupportFacets/scopeSupportFacetInfos.ts

@@ -225,6 +225,23 @@ export const scopeSupportFacetInfos: Record<
     scopeType: "string",
   },
 
+  "textFragment.comment.line": {
+    description: "Text fragment consisting of a line comment",
+    scopeType: "textFragment",
+  },
+  "textFragment.comment.block": {
+    description: "Text fragment consisting of a block comment",
+    scopeType: "textFragment",
+  },
+  "textFragment.string.singleLine": {
+    description: "Text fragment consisting of a single-line string",
+    scopeType: "textFragment",
+  },
+  "textFragment.string.multiLine": {
+    description: "Text fragment consisting of a multi-line string",
+    scopeType: "textFragment",
+  },
+
   "branch.if": {
     description: "An if/elif/else branch",
     scopeType: "branch",

packages/common/src/scopeSupportFacets/scopeSupportFacets.types.ts

@@ -57,6 +57,11 @@ const scopeSupportFacets = [
   "string.singleLine",
   "string.multiLine",
 
+  "textFragment.comment.line",
+  "textFragment.comment.block",
+  "textFragment.string.singleLine",
+  "textFragment.string.multiLine",
+
   "branch.if",
   "branch.if.iteration",
   "branch.try",
@@ -124,7 +129,6 @@ const scopeSupportFacets = [
   // selector
   // unit
   // collectionItem
-  // textFragment
 ] as const;
 
 const textualScopeSupportFacets = [

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

@@ -173,6 +173,8 @@ export const simpleScopeTypeTypes = [
   "notebookCell",
   // Talon
   "command",
+  // Private scope types
+  "textFragment",
 ] as const;
 
 export function isSimpleScopeType(

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

@@ -6,14 +6,11 @@ import {
 } from "@cursorless/common";
 import { basename, dirname, join } from "path";
 import { TreeSitterScopeHandler } from "../processTargets/modifiers/scopeHandlers";
-import { TreeSitterTextFragmentScopeHandler } from "../processTargets/modifiers/scopeHandlers/TreeSitterScopeHandler/TreeSitterTextFragmentScopeHandler";
-import { ScopeHandler } from "../processTargets/modifiers/scopeHandlers/scopeHandler.types";
 import { ide } from "../singletons/ide.singleton";
 import { TreeSitter } from "../typings/TreeSitter";
 import { matchAll } from "../util/regex";
 import { TreeSitterQuery } from "./TreeSitterQuery";
 import { validateQueryCaptures } from "./TreeSitterQuery/validateQueryCaptures";
-import { TEXT_FRAGMENT_CAPTURE_NAME } from "./captureNames";
 
 /**
  * Represents a language definition for a single language, including the
@@ -76,14 +73,6 @@ export class LanguageDefinition {
 
     return new TreeSitterScopeHandler(this.query, scopeType as SimpleScopeType);
   }
-
-  getTextFragmentScopeHandler(): ScopeHandler | undefined {
-    if (!this.query.captureNames.includes(TEXT_FRAGMENT_CAPTURE_NAME)) {
-      return undefined;
-    }
-
-    return new TreeSitterTextFragmentScopeHandler(this.query);
-  }
 }
 
 /**

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

@@ -81,11 +81,6 @@ const testCases: { name: string; isOk: boolean; content: string }[] = [
     isOk: false,
     content: "(if_statement) @statement.leading.start",
   },
-  {
-    name: "Text fragment removal",
-    isOk: false,
-    content: "(comment) @textFragment.removal",
-  },
 ];
 
 suite("validateQueryCaptures", function () {

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

@@ -2,7 +2,6 @@ import { showError, simpleScopeTypeTypes } from "@cursorless/common";
 import { ide } from "../../singletons/ide.singleton";
 
 const wildcard = "_";
-const textFragment = "textFragment";
 const captureNames = [wildcard, ...simpleScopeTypeTypes];
 
 const positionRelationships = ["prefix", "leading", "trailing"];
@@ -26,12 +25,6 @@ const rangeSuffixes = [
 
 const allowedCaptures = new Set<string>();
 
-allowedCaptures.add(textFragment);
-
-for (const suffix of rangeSuffixes) {
-  allowedCaptures.add(`${textFragment}.${suffix}`);
-}
-
 for (const captureName of captureNames) {
   // Wildcard is not allowed by itself without a relationship
   if (captureName !== wildcard) {

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

@@ -102,8 +102,9 @@ function processSurroundingPairCore(
 
   const textFragmentRange = (() => {
     // First try to use the text fragment scope handler if it exists
-    const textFragmentScopeHandler =
-      languageDefinition?.getTextFragmentScopeHandler();
+    const textFragmentScopeHandler = languageDefinition?.getScopeHandler({
+      type: "textFragment",
+    });
 
     if (textFragmentScopeHandler != null) {
       const containingScope = getContainingScopeTarget(
@@ -115,6 +116,7 @@ function processSurroundingPairCore(
       return containingScope?.[0].contentRange;
     }
 
+    // If we don't find a text fragment we fall back to the full document range
     return document.range;
   })();
 

packages/cursorless-engine/src/processTargets/modifiers/scopeHandlers/TreeSitterScopeHandler/TreeSitterTextFragmentScopeHandler.ts

@@ -157,6 +157,7 @@ function isLanguageSpecific(scopeType: ScopeType): boolean {
     case "namedParagraph":
     case "subParagraph":
     case "environment":
+    case "textFragment":
       return true;
 
     case "character":

packages/cursorless-engine/src/processTargets/modifiers/surroundingPair/index.ts

@@ -96,8 +96,9 @@ export const defaultSpokenFormMapCore: DefaultSpokenFormMapDefinition = {
     url: "link",
     notebookCell: "cell",
 
-    ["private.fieldAccess"]: isPrivate("access"),
     string: isPrivate("parse tree string"),
+    textFragment: isPrivate("text fragment"),
+    ["private.fieldAccess"]: isPrivate("access"),
     ["private.switchStatementSubject"]: isPrivate("subject"),
   },
   complexScopeTypeType: {