More docs

Author: pokey

packages/common/src/index.ts

@@ -52,6 +52,7 @@ export { default as DefaultMap } from "./util/DefaultMap";
 export * from "./types/GeneralizedRange";
 export * from "./types/RangeOffsets";
 export * from "./util/omitByDeep";
+export * from "./util/range";
 export * from "./testUtil/isTesting";
 export * from "./testUtil/testConstants";
 export * from "./testUtil/getFixturePaths";

packages/common/src/util/range.ts

@@ -0,0 +1,22 @@
+import { range as lodashRange } from "lodash";
+import { Range } from "../types/Range";
+import { TextEditor } from "../types/TextEditor";
+
+/**
+ * @param editor The editor containing the range
+ * @param range The range to get the line ranges for
+ * @returns A list of ranges, one for each line in the given range, with the
+ * first and last ranges trimmed to the start and end of the given range.
+ */
+export function getLineRanges(editor: TextEditor, range: Range): Range[] {
+  const { document } = editor;
+  const lineRanges = lodashRange(range.start.line, range.end.line + 1).map(
+    (lineNumber) => document.lineAt(lineNumber).range,
+  );
+  lineRanges[0] = lineRanges[0].with(range.start);
+  lineRanges[lineRanges.length - 1] = lineRanges[lineRanges.length - 1].with(
+    undefined,
+    range.end,
+  );
+  return lineRanges;
+}

packages/cursorless-vscode-e2e/src/suite/scopeVisualizer/checkAndResetFakes.ts

@@ -3,15 +3,15 @@ import * as sinon from "sinon";
 import {
   createDecorationTypeCallToPlainObject,
   setDecorationsCallToPlainObject,
-} from "./toPlainObject";
+} from "./spyCallsToPlainObject";
 import { Fakes, ExpectedArgs } from "./scopeVisualizerTest.types";
 
 export function checkAndResetFakes(fakes: Fakes, expected: ExpectedArgs) {
-  const actual = getAndResetFakes(fakes);
+  const actual = getSpyCallsAndResetFakes(fakes);
   assert.deepStrictEqual(actual, expected, JSON.stringify(actual));
 }
 
-export function getAndResetFakes({
+function getSpyCallsAndResetFakes({
   createTextEditorDecorationType,
   setDecorations,
   dispose,

packages/cursorless-vscode-e2e/src/suite/scopeVisualizer/colorConfig.ts

@@ -1,5 +1,10 @@
 import { ScopeVisualizerColorConfig } from "@cursorless/vscode-common";
 
+/**
+ * Fake color config to use for testing. We use an alpha of 50% and try to use
+ * different rgb channels where possible to make it easier to see what happens
+ * when we blend colors.
+ */
 export const COLOR_CONFIG: ScopeVisualizerColorConfig = {
   dark: {
     content: {

packages/cursorless-vscode-e2e/src/suite/scopeVisualizer/injectFakes.ts

@@ -9,7 +9,7 @@ import {
 } from "./scopeVisualizerTest.types";
 
 export async function injectFakes(): Promise<Fakes> {
-  const { vscodeApi: vscodeApi } = (await getCursorlessApi()).testHelpers!;
+  const { vscodeApi } = (await getCursorlessApi()).testHelpers!;
 
   const dispose = sinon.fake<[number], void>();
 

packages/cursorless-vscode-e2e/src/suite/scopeVisualizer/runBasicMultilineContentTest.png

@@ -4,6 +4,13 @@ import { checkAndResetFakes } from "./checkAndResetFakes";
 import { injectFakes } from "./injectFakes";
 import { ExpectedArgs } from "./scopeVisualizerTest.types";
 
+/**
+ * Tests that the scope visualizer works with multiline content, by
+ * ensuring that the correct decorations are applied so that it looks
+ * as follows:
+ *
+ * ![basic multiline content](./runBasicMultilineContentTest.png)
+ */
 export async function runBasicMultilineContentTest() {
   await openNewEditor(contents, {
     languageId: "typescript",

packages/cursorless-vscode-e2e/src/suite/scopeVisualizer/runBasicMultilineContentTest.ts

@@ -4,6 +4,12 @@ import { checkAndResetFakes } from "./checkAndResetFakes";
 import { injectFakes } from "./injectFakes";
 import { ExpectedArgs } from "./scopeVisualizerTest.types";
 
+/**
+ * Tests that the scope visualizer works with removal ranges, by ensuring that
+ * the correct decorations are applied so that it looks as follows:
+ *
+ * ![basic removal](./runBasicRemovalTest.png)
+ */
 export async function runBasicRemovalTest() {
   await openNewEditor("aaa bbb");