Add minimum version to test fixture upgrader (#2427)

- First step of #2282



## Checklist

- [-] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [x] 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)
- [x] I have not broken the cheatsheet

Author: pokey

docs/contributing/test-case-recorder.md

@@ -79,9 +79,19 @@ Recorded tests will automatically be picked up and run with the normal tests.
 
 To clean up the formatting of all of the yaml test cases, run `pnpm transform-recorded-tests`
 
-### Upgrading fixtures
+### Canonicalizing fixtures
 
-To upgrade all the test fixtures to the latest command version, run the command `pnpm transform-recorded-tests --upgrade`. This command should be idempotent.
+To upgrade test fixtures to their canonical, latest form, run the command `pnpm transform-recorded-tests --canonicalize <paths>`. This command should be idempotent.
+
+### Partially upgrading fixtures
+
+We periodically upgrade test case fixtures to use the version of our command payload from one year ago. To do so, proceed as follows:
+
+1. Look at the blame of the big switch statement in the `upgradeCommand` function in [`canonicalizeAndValidateCommand`](../../packages/cursorless-engine/src/core/commandVersionUpgrades/canonicalizeAndValidateCommand.ts). You can do this on the web [here](https://github.com/cursorless-dev/cursorless/blame/main/packages/cursorless-engine/src/core/commandVersionUpgrades/canonicalizeAndValidateCommand.ts)
+1. Find the newest `case` branch that is at least one year old
+1. Look at the version number that is the guard of that case branch; the minimum number should be that + 1
+1. Run `pnpm transform-recorded-tests --upgrade --minimum-version 5`, where 5 is the minimum version number you found
+1. Open a PR with the changes
 
 ### Custom transformation
 

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

@@ -16,6 +16,8 @@ export type CommandLatest = Command & {
   version: typeof LATEST_VERSION;
 };
 
+export type CommandVersion = Command["version"];
+
 export type Command =
   | CommandV0
   | CommandV1

packages/cursorless-engine/src/core/commandVersionUpgrades/canonicalizeAndValidateCommand.ts

@@ -2,12 +2,13 @@ import {
   ActionType,
   Command,
   CommandComplete,
-  CommandLatest,
+  CommandVersion,
   EnforceUndefined,
   LATEST_VERSION,
   OutdatedExtensionError,
   PartialTargetDescriptor,
 } from "@cursorless/common";
+import { produce } from "immer";
 import { getPartialTargetDescriptors } from "../../util/getPartialTargetDescriptors";
 import canonicalizeTargetsInPlace from "./canonicalizeTargetsInPlace";
 import { upgradeV0ToV1 } from "./upgradeV0ToV1";
@@ -17,7 +18,6 @@ import { upgradeV3ToV4 } from "./upgradeV3ToV4";
 import { upgradeV4ToV5 } from "./upgradeV4ToV5/upgradeV4ToV5";
 import { upgradeV5ToV6 } from "./upgradeV5ToV6";
 import { upgradeV6ToV7 } from "./upgradeV6ToV7";
-import { produce } from "immer";
 
 /**
  * Given a command argument which comes from the client, normalize it so that it
@@ -29,7 +29,7 @@ import { produce } from "immer";
 export function canonicalizeAndValidateCommand(
   command: Command,
 ): EnforceUndefined<CommandComplete> {
-  const commandUpgraded = upgradeCommand(command);
+  const commandUpgraded = upgradeCommand(command, LATEST_VERSION);
   const { action, usePrePhraseSnapshot = false, spokenForm } = commandUpgraded;
 
   return {
@@ -45,12 +45,15 @@ export function canonicalizeAndValidateCommand(
   };
 }
 
-function upgradeCommand(command: Command): CommandLatest {
+export function upgradeCommand<V extends CommandVersion>(
+  command: Command,
+  minimumVersion: V,
+): Command & { version: V } {
   if (command.version > LATEST_VERSION) {
     throw new OutdatedExtensionError();
   }
 
-  while (command.version < LATEST_VERSION) {
+  while (command.version < minimumVersion) {
     switch (command.version) {
       case 0:
         command = upgradeV0ToV1(command);
@@ -80,11 +83,9 @@ function upgradeCommand(command: Command): CommandLatest {
     }
   }
 
-  if (command.version !== LATEST_VERSION) {
-    throw new Error("Command is not latest version");
-  }
-
-  return command;
+  return command as Command & {
+    version: V;
+  };
 }
 
 /**

packages/cursorless-engine/src/scripts/transformRecordedTests/checkMarks.ts

@@ -4,11 +4,11 @@ import { injectIde } from "../../singletons/ide.singleton";
 import tokenGraphemeSplitter from "../../singletons/tokenGraphemeSplitter.singleton";
 import { extractTargetKeys } from "../../testUtil/extractTargetKeys";
 import { getPartialTargetDescriptors } from "../../util/getPartialTargetDescriptors";
-import { upgrade } from "./transformations/upgrade";
 import assert from "assert";
+import { canonicalize } from "./transformations/canonicalize";
 
 export function checkMarks(originalFixture: TestCaseFixtureLegacy): undefined {
-  const command = upgrade(originalFixture).command;
+  const command = canonicalize(originalFixture).command;
 
   injectIde(new FakeIDE());
   const graphemeSplitter = tokenGraphemeSplitter();

packages/cursorless-engine/src/scripts/transformRecordedTests/index.ts

@@ -1,28 +1,39 @@
-import { getRecordedTestPaths } from "@cursorless/common";
+import {
+  CommandVersion,
+  LATEST_VERSION,
+  TestCaseFixtureLegacy,
+  getRecordedTestPaths,
+} from "@cursorless/common";
 import { identity } from "./transformations/identity";
 import { upgrade } from "./transformations/upgrade";
 import { transformFile } from "./transformFile";
 import { FixtureTransformation } from "./types";
 import { upgradeDecorations } from "./upgradeDecorations";
 import { checkMarks } from "./checkMarks";
+import { canonicalize } from "./transformations/canonicalize";
 
 const AVAILABLE_TRANSFORMATIONS: Record<string, FixtureTransformation> = {
   upgrade,
+  canonicalize,
   format: identity,
   ["check-marks"]: checkMarks,
   custom: upgradeDecorations,
 };
 
 async function main(args: string[]) {
-  const [transformationName, paths] = args?.[0]?.startsWith("--")
-    ? [args[0].slice(2), args.slice(1)]
-    : [null, args];
+  const { transformationName, minimumVersion, paths } =
+    parseCommandLineArguments(args);
 
-  const transformation =
+  let transformation =
     transformationName == null
       ? identity
       : AVAILABLE_TRANSFORMATIONS[transformationName];
 
+  if (transformation === upgrade && minimumVersion != null) {
+    transformation = (originalFixture: TestCaseFixtureLegacy) =>
+      upgrade(originalFixture, minimumVersion);
+  }
+
   if (transformation == null) {
     throw new Error(`Unknown transformation ${transformationName}`);
   }
@@ -47,4 +58,41 @@ async function main(args: string[]) {
   }
 }
 
+function parseCommandLineArguments(args: string[]) {
+  const paths = [];
+  let transformationName: string | undefined = undefined;
+  let minimumVersion: CommandVersion | undefined = undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const flagName = arg.slice(2);
+
+      if (flagName in AVAILABLE_TRANSFORMATIONS) {
+        transformationName = flagName;
+        continue;
+      }
+
+      if (flagName === "minimum-version") {
+        const minimumVersionUnchecked = parseInt(args[i + 1]);
+        if (
+          minimumVersionUnchecked < 0 ||
+          minimumVersionUnchecked > LATEST_VERSION
+        ) {
+          throw new Error(
+            `Minimum version must be between 0 and ${LATEST_VERSION} inclusive`,
+          );
+        }
+        minimumVersion = minimumVersionUnchecked as CommandVersion;
+        i++;
+        continue;
+      }
+
+      throw new Error(`Unknown flag ${flagName}`);
+    }
+    paths.push(arg);
+  }
+
+  return { transformationName, minimumVersion, paths };
+}
+
 main(process.argv.slice(2));

packages/cursorless-engine/src/scripts/transformRecordedTests/transformations/canonicalize.ts

@@ -0,0 +1,9 @@
+import { TestCaseFixture, TestCaseFixtureLegacy } from "@cursorless/common";
+import { canonicalizeAndValidateCommand } from "../../../core/commandVersionUpgrades/canonicalizeAndValidateCommand";
+
+export function canonicalize(fixture: TestCaseFixtureLegacy): TestCaseFixture {
+  return {
+    ...fixture,
+    command: canonicalizeAndValidateCommand(fixture.command),
+  };
+}

packages/cursorless-engine/src/scripts/transformRecordedTests/transformations/upgrade.ts

@@ -1,9 +1,16 @@
-import { TestCaseFixture, TestCaseFixtureLegacy } from "@cursorless/common";
-import { canonicalizeAndValidateCommand } from "../../../core/commandVersionUpgrades/canonicalizeAndValidateCommand";
+import {
+  CommandVersion,
+  LATEST_VERSION,
+  TestCaseFixtureLegacy,
+} from "@cursorless/common";
+import { upgradeCommand } from "../../../core/commandVersionUpgrades/canonicalizeAndValidateCommand";
 
-export function upgrade(fixture: TestCaseFixtureLegacy): TestCaseFixture {
+export function upgrade(
+  fixture: TestCaseFixtureLegacy,
+  minimumVersion: CommandVersion = LATEST_VERSION,
+): TestCaseFixtureLegacy {
   return {
     ...fixture,
-    command: canonicalizeAndValidateCommand(fixture.command),
+    command: upgradeCommand(fixture.command, minimumVersion),
   };
 }