Add includeDescendantScopes field to scope handlers (#1647)

- Required by #1650
- Note that we have no tests here, but it is tested in
#1653

## Checklist

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

Author: pokey

packages/cursorless-engine/src/processTargets/modifiers/scopeHandlers/BaseScopeHandler.ts

@@ -14,6 +14,7 @@ const DEFAULT_REQUIREMENTS: Omit<ScopeIteratorRequirements, "distalPosition"> =
     containment: null,
     allowAdjacentScopes: false,
     skipAncestorScopes: false,
+    includeDescendantScopes: false,
   };
 
 /**

packages/cursorless-engine/src/processTargets/modifiers/scopeHandlers/scopeHandler.types.ts

@@ -149,4 +149,17 @@ export interface ScopeIteratorRequirements {
    * @default false
    */
   skipAncestorScopes: boolean;
+
+  /**
+   * Indicates whether the ScopeHandler should yield a scope if it is a
+   * descendant of any scope that has been previously yielded.
+   *
+   * - `true` means that descendant scopes of any previously yielded scope will
+   *   be yielded.
+   * - `false` means that descendant scopes of any previously yielded scope will
+   *   not be yielded.
+   *
+   * @default false
+   */
+  includeDescendantScopes: boolean;
 }

packages/cursorless-engine/src/processTargets/modifiers/scopeHandlers/shouldYieldScope.ts

@@ -31,9 +31,17 @@ export function shouldYieldScope(
     checkRequirements(initialPosition, requirements, previousScope, scope) &&
     // Note that we're using `currentPosition` instead of `initialPosition`
     // below, because we want to filter out scopes that are strictly contained
-    // by previous scopes.
+    // by previous scopes.  However, if we want to include descendant scopes,
+    // then we do use the initial position
     (previousScope == null ||
-      compareTargetScopes(direction, currentPosition, previousScope, scope) < 0)
+      compareTargetScopes(
+        direction,
+        requirements.includeDescendantScopes
+          ? initialPosition
+          : currentPosition,
+        previousScope,
+        scope,
+      ) < 0)
   );
 }