Notebook cell scope provider (#2693)

Fixes #1053

Related #1052

I'm sure how we're gonna support the python comment style cells

```py
# %%
print("hello")
```

We have tests for them:
https://github.com/cursorless-dev/cursorless/blob/56ad4c5cef3f8c8267a098a375cf9139cbbfb0ff/data/fixtures/recorded/selectionTypes/pourCell.yml
But they are not a cell scope you can actually target. Tree sitter just
sees these as a comment and a function call. We could
1. Remove them. I'm probably leaning towards this.
2. Try to use regular expression to actually support them properly. That
means we're back to language specific implementations in typescript.
3. Do what we did before and just yield the current position as a
notebook target. Feels very hacky and not something I would like to do.

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

---------

Co-authored-by: Phil Cohen <phillip@phillip.io>

Author: AndreasArvidsson

data/fixtures/recorded/selectionTypes/drinkCell.yml

@@ -1,4 +1,5 @@
 import type { GeneralizedRange } from "../types/GeneralizedRange";
+import type { NotebookEditor } from "../types/NotebookEditor";
 import type { TextDocument } from "../types/TextDocument";
 import type { EditableTextEditor, TextEditor } from "../types/TextEditor";
 import type { Capabilities } from "./types/Capabilities";
@@ -17,9 +18,9 @@ import type {
   RunMode,
   WorkspaceFolder,
 } from "./types/ide.types";
+import type { KeyValueStore } from "./types/KeyValueStore";
 import type { Messages } from "./types/Messages";
 import type { QuickPickOptions } from "./types/QuickPickOptions";
-import type { KeyValueStore } from "./types/KeyValueStore";
 
 export default class PassthroughIDEBase implements IDE {
   configuration: Configuration;
@@ -123,6 +124,10 @@ export default class PassthroughIDEBase implements IDE {
     return this.original.visibleTextEditors;
   }
 
+  public get visibleNotebookEditors(): NotebookEditor[] {
+    return this.original.visibleNotebookEditors;
+  }
+
   public get cursorlessVersion(): string {
     return this.original.cursorlessVersion;
   }

data/fixtures/recorded/selectionTypes/drinkCellEach.yml

@@ -1,5 +1,5 @@
 import { pull } from "lodash-es";
-import type { EditableTextEditor, TextEditor } from "../..";
+import type { EditableTextEditor, NotebookEditor, TextEditor } from "../..";
 import type { GeneralizedRange } from "../../types/GeneralizedRange";
 import type { TextDocument } from "../../types/TextDocument";
 import type { TextDocumentChangeEvent } from "../types/Events";
@@ -82,6 +82,10 @@ export class FakeIDE implements IDE {
     throw Error("Not implemented");
   }
 
+  get visibleNotebookEditors(): NotebookEditor[] {
+    throw Error("Not implemented");
+  }
+
   public getEditableTextEditor(_editor: TextEditor): EditableTextEditor {
     throw Error("Not implemented");
   }

data/fixtures/recorded/selectionTypes/pourCell.yml

@@ -1,10 +1,11 @@
+import type { URI } from "vscode-uri";
 import type {
   EditableTextEditor,
   InputBoxOptions,
+  NotebookEditor,
   TextDocument,
   TextEditor,
 } from "../..";
-import type { URI } from "vscode-uri";
 import type { GeneralizedRange } from "../../types/GeneralizedRange";
 import type { Capabilities } from "./Capabilities";
 import type { Clipboard } from "./Clipboard";
@@ -16,9 +17,9 @@ import type {
   TextEditorVisibleRangesChangeEvent,
 } from "./events.types";
 import type { FlashDescriptor } from "./FlashDescriptor";
+import type { KeyValueStore } from "./KeyValueStore";
 import type { Messages } from "./Messages";
 import type { QuickPickOptions } from "./QuickPickOptions";
-import type { KeyValueStore } from "./KeyValueStore";
 
 export type RunMode = "production" | "development" | "test";
 export type HighlightId = string;
@@ -79,6 +80,11 @@ export interface IDE {
    */
   readonly visibleTextEditors: TextEditor[];
 
+  /**
+   * The currently visible notebook editors or an empty array.
+   */
+  readonly visibleNotebookEditors: NotebookEditor[];
+
   /**
    * The capabilities of the IDE
    */

data/fixtures/recorded/selectionTypes/pourCellEach.yml

@@ -14,19 +14,19 @@ export * from "./ide/types/Clipboard";
 export * from "./ide/types/CommandHistoryStorage";
 export * from "./ide/types/CommandId";
 export * from "./ide/types/Configuration";
-export * from "./ide/types/events.types";
 export * from "./ide/types/Events";
+export * from "./ide/types/events.types";
 export * from "./ide/types/FileSystem.types";
 export * from "./ide/types/FlashDescriptor";
 export * from "./ide/types/Hats";
 export * from "./ide/types/HatStability";
 export * from "./ide/types/hatStyles.types";
 export * from "./ide/types/ide.types";
+export * from "./ide/types/KeyValueStore";
 export * from "./ide/types/Messages";
 export * from "./ide/types/Paths";
 export * from "./ide/types/QuickPickOptions";
 export * from "./ide/types/RawTreeSitterQueryProvider";
-export * from "./ide/types/KeyValueStore";
 export * from "./ide/types/TutorialContentProvider";
 export * from "./ide/util/messages";
 export * from "./scopeSupportFacets/languageScopeSupport";
@@ -66,6 +66,8 @@ export * from "./types/Edit";
 export * from "./types/GeneralizedRange";
 export * from "./types/HatTokenMap";
 export * from "./types/InputBoxOptions";
+export * from "./types/NotebookCell";
+export * from "./types/NotebookEditor";
 export * from "./types/Position";
 export * from "./types/Range";
 export * from "./types/RangeExpansionBehavior";

packages/common/src/ide/PassthroughIDEBase.ts

@@ -0,0 +1,32 @@
+import type { TextDocument } from "./TextDocument";
+
+export interface NotebookCell {
+  /**
+   * The index of this cell in its containing notebook. The
+   * index is updated when a cell is moved within its notebook. The index is `-1`
+   * when the cell has been removed from its notebook.
+   */
+  readonly index: number;
+
+  /**
+   * The kind of this cell.
+   */
+  readonly kind: NotebookCellKind;
+
+  /**
+   * The {@link TextDocument} of this cell.
+   */
+  readonly document: TextDocument;
+}
+
+export enum NotebookCellKind {
+  /**
+   * A markup-cell is formatted source that is used for display.
+   */
+  Markup = 1,
+
+  /**
+   * A code-cell.
+   */
+  Code = 2,
+}

packages/common/src/ide/fake/FakeIDE.ts

@@ -0,0 +1,22 @@
+import type { URI } from "vscode-uri";
+import type { NotebookCell } from "./NotebookCell";
+
+export interface NotebookEditor {
+  /**
+   * The associated uri for this document.
+   *
+   * *Note* that most documents use the `file`-scheme, which means they are files on disk. However, **not** all documents are
+   * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk.
+   */
+  readonly uri: URI;
+
+  /**
+   * The number of cells in the notebook.
+   */
+  readonly cellCount: number;
+
+  /**
+   * The cells of this notebook.
+   */
+  readonly cells: NotebookCell[];
+}