Merge branch 'nvim-talon' into lua-tests

Author: Cedric Halbronn

.github/CODEOWNERS

@@ -1,4 +1,7 @@
-*       @pokey @AndreasArvidsson
+*       @pokey @AndreasArvidsson @phillco
 
-*keyboard* @pokey @AndreasArvidsson @josharian
-*Keyboard* @pokey @AndreasArvidsson @josharian
+*keyboard* @pokey @AndreasArvidsson @phillco @josharian
+*Keyboard* @pokey @AndreasArvidsson @phillco @josharian
+
+*neovim* @pokey @AndreasArvidsson @saidelike @fidgetingbits
+*Neovim* @pokey @AndreasArvidsson @saidelike @fidgetingbits

.github/workflows/test.yml

@@ -24,6 +24,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     env:
       APP_VERSION: ${{ matrix.app_version }}
+      NEOVIM_VERSION: ${{ matrix.app_version == 'stable' && 'stable' || 'v0.10.0' }}
       VSCODE_CRASH_DIR: ${{ github.workspace }}/artifacts/dumps
       VSCODE_LOGS_DIR: ${{ github.workspace }}/artifacts/logs
       CURSORLESS_REPO_ROOT: ${{ github.workspace }}
@@ -46,14 +47,13 @@ jobs:
         if: runner.os != 'Linux'
       - run: bash -x scripts/install-neovim-dependencies.sh
       - uses: rhysd/action-setup-vim@v1
-        if: matrix.app_version != 'legacy'
         id: vim
         with:
-          version: ${{ matrix.app_version }}
+          version: ${{ env.NEOVIM_VERSION }}
           neovim: true
       - name: Run neovim tests
-        run: xvfb-run -a pnpm -F @cursorless/test-harness testNeovim
-        if: runner.os == 'Linux' && matrix.app_version == 'stable'
+        run: xvfb-run -a pnpm -F @cursorless/test-harness test:neovim
+        if: runner.os == 'Linux'
         env:
           NEOVIM_PATH: ${{ steps.vim.outputs.executable }}
       - uses: ./.github/actions/test-neovim-lua/

.vscode/tasks.json

@@ -204,23 +204,21 @@
     {
       "label": "Neovim: Launch neovim",
       "type": "process",
-      "windows": {
-        "command": "powershell",
-        "args": [
-          "(New-Object -ComObject WScript.Shell).Run(\"\"\"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.bat\"\"\", 1, $false)"
-        ]
-      },
+      "command": "packages/cursorless-neovim/scripts/linux-terminal.sh",
+      "args": [
+        "${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} development"
+      ],
       "osx": {
         "command": "osascript",
         "args": [
           "-e",
           "tell app \"Terminal\" to do script \"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} development\" activate"
         ]
       },
-      "linux": {
-        "command": "packages/cursorless-neovim/scripts/linux-terminal.sh",
+      "windows": {
+        "command": "powershell",
         "args": [
-          "${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} development"
+          "(New-Object -ComObject WScript.Shell).Run(\"\"\"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.bat\"\"\", 1, $false)"
         ]
       },
       "group": "build",
@@ -237,23 +235,21 @@
     {
       "label": "Neovim: Launch neovim (test)",
       "type": "process",
-      "windows": {
-        "command": "powershell",
-        "args": [
-          "(New-Object -ComObject WScript.Shell).Run(\"\"\"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.bat\"\"\", 1, $false)"
-        ]
-      },
+      "command": "packages/cursorless-neovim/scripts/linux-terminal.sh",
+      "args": [
+        "${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} test"
+      ],
       "osx": {
         "command": "osascript",
         "args": [
           "-e",
           "tell app \"Terminal\" to do script \"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} test\" activate"
         ]
       },
-      "linux": {
-        "command": "packages/cursorless-neovim/scripts/linux-terminal.sh",
+      "windows": {
+        "command": "powershell",
         "args": [
-          "${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.sh ${workspaceFolder} test"
+          "(New-Object -ComObject WScript.Shell).Run(\"\"\"${workspaceFolder}/packages/cursorless-neovim/scripts/debug-neovim.bat\"\"\", 1, $false)"
         ]
       },
       "group": "build",
@@ -270,20 +266,13 @@
     {
       "label": "Neovim: Show logs",
       "type": "process",
-      "osx": {
-        "command": "tail",
-        "args": [
-          "-f",
-          "${workspaceFolder}/packages/cursorless-neovim/out/nvim_node.log"
-        ]
-      },
-      "linux": {
-        "command": "tail",
-        "args": [
-          "-f",
-          "${workspaceFolder}/packages/cursorless-neovim/out/nvim_node.log"
-        ]
-      }
+      "command": "tail",
+      "args": [
+        "-f",
+        "${workspaceFolder}/packages/cursorless-neovim/out/nvim_node.log"
+      ],
+      "problemMatcher": [],
+      "isBackground": true
       // NOTE: We don't have a way on Windows atm due to command with argument inside Run() not working
       // so we need to show logs outside of vscode (see #2454)
     },

cursorless.nvim/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing
+
+Welcome! So glad you've decided to help make Cursorless in Neovim better.
+
+Note that Cursorless is maintained as a monorepo, hosted at [`cursorless`](https://github.com/cursorless-dev/cursorless), and the source of truth for all of the files here lives there, so that's where you'll want to file a PR. We automatically deploy from our monorepo to the [cursorless.nvim repo](https://github.com/hands-free-vim/cursorless.nvim) in CI.
+
+See [the Cursorless neovim contributor docs](https://www.cursorless.org/docs/contributing/cursorless-in-neovim/) to get started.

cursorless.nvim/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cedric Halbronn, Brandon Virgil Rule, et al.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cursorless.nvim/README.md

@@ -20,7 +20,7 @@
 
 # cursorless.nvim
 
-Neovim plugin to support Cursorless
+Very experimental Neovim plugin providing partial Cursorless support. We support much of the core functionality, but many features are not yet implemented, in particular hats and language-specific scopes. Expect some rough edges, but please give it a try, and if you like it, consider [contributing](https://www.cursorless.org/docs/contributing/cursorless-in-neovim/)!
 
 ## Prerequisites
 
@@ -109,6 +109,10 @@ Some Linux package managers ship with a version of `nvim` too old for Lazy. If t
 
 If you are on Linux, avoid using the snap package for `npm` as it may not be able to globally expose the neovim npm package due to sandboxing. If this is the case, install node via another method (nvm, brew, etc).
 
-## Contributors
+## Contributing
 
-Welcome! So glad you've decided to help make Cursorless in Neovim better. You'll want to start by getting [set up](https://github.com/saidelike/cursorless/blob/nvim-talon/docs/contributing/cursorless-in-neovim.md). You may also find the [Neovim API docs](https://neovim.io/doc/user/api.html) helpful to learn about Neovim extension development.
+Welcome! So glad you've decided to help make Cursorless in Neovim better.
+
+Note that Cursorless is maintained as a monorepo, hosted at [`cursorless`](https://github.com/cursorless-dev/cursorless), and the source of truth for all of the files here lives there, so that's where you'll want to file a PR. We automatically deploy from our monorepo to the [cursorless.nvim repo](https://github.com/hands-free-vim/cursorless.nvim) in CI.
+
+See [the Cursorless neovim contributor docs](https://www.cursorless.org/docs/contributing/cursorless-in-neovim/) to get started.

docs/contributing/CONTRIBUTING.md

@@ -14,7 +14,7 @@ extension](#running--testing-extension-locally). You may also find the [VSCode A
 
 ### Steps
 
-1. Clone [`cursorless`](https://github.com/cursorless-dev/cursorless)
+1. Clone [`cursorless`](https://github.com/cursorless-dev/cursorless) locally. Note that it doesn't matter where you clone it, as long as you _**do not**_ clone it into your Talon user directory.
 2. Open the newly created `cursorless` directory in VSCode. If you're on Windows, don't use WSL (see [#919](https://github.com/cursorless-dev/cursorless/issues/919) for discussion / workaround).
 3. Run the following in the terminal:
 

docs/contributing/architecture/tests.md renamed to docs/contributing/architecture/neovim-test-infrastructure.md

@@ -1,24 +1,22 @@
-# Tests
+# Neovim test infrastructure
 
-Tests in Cursorless are done in various ways depending on what is tested.
+We'll start with a high-level overview of the architecture of the Cursorless tests for neovim, and then we'll dive into the details.
 
-1. **Cursorless tests for VSCode**: tests the actions (`take`, `chuck`, etc.) inside VSCode.
+## Neovim tests
 
-2. **Cursorless unit tests**: tests specific TypeScript functions (`toggle decorations`, `visible multiple regions`, etc.). These tests don't rely on VSCode or neovim.
-
-3. **Cursorless tests for neovim**: tests the actions (`take`, `chuck`, etc.) inside neovim. 99% of them are the same as the "Cursorless tests for VSCode" except some new ones are needed in order to test all actions, due to no hats being supported yet in neovim (and the fact that lots of "Cursorless tests for VSCode" rely on hats).
+Here is the call path when running Neovim tests locally. Note that `->` indicates one file calling another file:
 
 ```
-// 3.1 Cursorless tests for neovim locally
 launch.json -> .vscode/tasks.json -> nvim -u init.lua
 
 init.lua
   -> CursorlessLoadExtension()
-  -> TestHarnessRun() -> run() -> runAllTests() -> Mocha + packages/cursorless-neovim-e2e/src/suite/recorded.neovim.test.ts
+  -> TestHarnessRun() -> run() -> runAllTests() -> Mocha -> packages/cursorless-neovim-e2e/src/suite/recorded.neovim.test.ts
 ```
 
+And here is the call path when running Neovim tests on CI:
+
 ```
-// 3.2 Cursorless tests for neovim on CI
 .github/workflows/test.yml -> packages/test-harness/package.json -> my-ts-node src/scripts/runNeovimTestsCI.ts -> packages/test-harness/src/launchNeovimAndRunTests.ts
 
 launchNeovimAndRunTests.ts
@@ -31,40 +29,7 @@ packages/test-harness/src/config/init.lua
   -> TestHarnessRun() -> run() -> runAllTests() -> Mocha + packages/cursorless-neovim-e2e/src/suite/recorded.neovim.test.ts
 ```
 
-4. **Lua unit tests for neovim**: tests lua functions implemented in cursorless.nvim. These tests are
-   executed inside neovim.
-
-```
-// 4.1 Lua unit tests for neovim locally
-launch.json -> .vscode/tasks.json -> cd cursorless.nvim && busted --run unit
-
-cursorless.nvim/.busted
-  -> lua interpreter: cursorless.nvim/test/nvim-shim.sh -> nvim -l <spec_script>
-  -> test specification files: cursorless.nvim/test/unit/*_spec.lua
-```
-
-```
-// 4.2 Lua unit tests for neovim on CI
-.github/workflows/test.yml -> .github/actions/test-neovim-lua/action.yml -> cd cursorless.nvim && busted --run unit
-
-cursorless.nvim/.busted
-  -> lua interpreter: cursorless.nvim/test/nvim-shim.sh -> nvim -l <spec_script>
-  -> test specification files: cursorless.nvim/test/unit/*_spec.lua
-```
-
-5. **Cursorless tests for Talon**: XXX
-
-## 1. Cursorless tests for VSCode
-
-XXX
-
-## 2. Cursorless unit tests
-
-XXX
-
-## 3. Cursorless tests for neovim
-
-### 3.1 Cursorless tests for neovim locally
+### Running Neovim tests locally
 
 This is supported on Windows, Linux and OSX.
 
@@ -236,21 +201,21 @@ async function runTestsInDir(
 
 Consequently, the recorded tests from `data/fixtures/recorded/` are executed when `packages/cursorless-neovim-e2e/src/suite/recorded.neovim.test.ts` is invoked.
 
-### 3.2 Cursorless tests for neovim on CI
+### Running Neovim tests on CI
 
 This is supported on Linux only.
 
 It starts from `.github/workflows/test.yml` which currently only tests the latest stable neovim version on Linux:
 
 ```yml
-run: xvfb-run -a pnpm -F @cursorless/test-harness testNeovim
+run: xvfb-run -a pnpm -F @cursorless/test-harness test:neovim
 if: runner.os == 'Linux' && matrix.app_version == 'stable'
 ```
 
 This triggers the script in `packages/test-harness/package.json`:
 
 ```json
-"testNeovim": "env CURSORLESS_MODE=test my-ts-node src/scripts/runNeovimTestsCI.ts",
+"test:neovim": "env CURSORLESS_MODE=test my-ts-node src/scripts/runNeovimTestsCI.ts",
 ```
 
 This ends up calling the default function from `package/test-harness/src/scripts/runNeovimTestsCI.ts` which calls `launchNeovimAndRunTests()` from `packages/test-harness/src/launchNeovimAndRunTests.ts`:
@@ -310,14 +275,33 @@ NOTE: Because `NVIM_NODE_HOST_DEBUG` is not set on CI, `nvim` loads entirely rig
 
 NOTE: CI uses `dist/cursorless.nvim/` (and not `cursorless.nvim/`), since the symlinks in `cursorless.nvim/` are only created locally in order to get symbols loaded, which we don't need on CI.
 
-## 4. Lua unit tests for neovim
+## Lua unit tests
 
 This is supported on Linux only, both locally and on CI.
 
+Here is the call path when running lua unit tests locally. Note that `->` indicates one file calling another file:
+
+```
+launch.json -> .vscode/tasks.json -> cd cursorless.nvim && busted --run unit
+cursorless.nvim/.busted
+  -> lua interpreter: cursorless.nvim/test/nvim-shim.sh -> nvim -l <spec_script>
+  -> test specification files: cursorless.nvim/test/unit/*_spec.lua
+```
+
+And here is the call path when running lua unit tests on CI:
+
+```
+.github/workflows/test.yml -> .github/actions/test-neovim-lua/action.yml -> cd cursorless.nvim && busted --run unit
+cursorless.nvim/.busted
+  -> lua interpreter: cursorless.nvim/test/nvim-shim.sh -> nvim -l <spec_script>
+  -> test specification files: cursorless.nvim/test/unit/*_spec.lua
+```
+
+### Running lua unit tests
+
 Many of the cursorless.nvim lua functions are run in order to complete Cursorless actions and so are already
 indirectly tested by the tests described in the [previous section](#3-cursorless-tests-for-neovim). Nevertheless, we run
 more specific unit tests in order to give better visibility into exactly which functions are failing.
-
 The [busted](https://github.com/lunarmodules/busted) framework is used to test lua functions defined in cursorless.nvim.
 This relies on a `cursorless.nvim/.busted` file which directs busted to use a lua interpreter and test specifications files:
 
@@ -336,17 +320,10 @@ The `.busted` file declares the `cursorless.nvim/test/nvim-shim.sh` shell wrappe
 Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) environment variables (Linux
 only) pointing to a temp directory. This allows loading cursorless.nvim, any helpers and (optional) plugins needed to run
 the tests. Consequently, the cursorless.nvim lua functions are exposed to the tests. Afterwards, the shim will use `nvim -l <spec_script>` for each of the [lua test specifications scripts](https://neovim.io/doc/user/starting.html#-l).
-
 The `.busted` file declares that test specifications files are in
 `cursorless.nvim/test/unit/`. Any file in that folder ending with `_spec.lua` contains tests and will be executed
 by neovim's lua interpreter.
-
 NOTE: Different tests rely on
 the same custom test helper functions. These functions are exposed as globals in a file called `helpers.lua` placed in `nvim/plugin/` inside the isolated XDG environment. These helpers themselves also have their own unit tests that will be run by busted.
-
 This busted setup was inspired by this [blog
 post](https://hiphish.github.io/blog/2024/01/29/testing-neovim-plugins-with-busted/), which goes into greater detail.
-
-## 5. Cursorless tests for Talon
-
-XXX

docs/contributing/cursorless-in-neovim.md

@@ -1,6 +1,8 @@
 # Cursorless in Neovim
 
-This document describes how to get set up to work on the Cursorless neovim plugin.
+This document describes how to get set up to work on the Cursorless neovim plugin. You may also find the [Neovim API docs](https://neovim.io/doc/user/api.html) helpful to learn about Neovim extension development.
+
+Note that Cursorless is maintained as a monorepo, hosted at [`cursorless`](https://github.com/cursorless-dev/cursorless), and the source of truth for all of the files in cursorless.nvim lives there. We automatically deploy from our monorepo to the [cursorless.nvim repo](https://github.com/hands-free-vim/cursorless.nvim) in CI.
 
 ## Initial setup
 
@@ -50,7 +52,7 @@ running: `busted --run unit`. These tests currently only work on Linux.
 
 ## Sending pull requests
 
-The [cursorless.nvim](https://github.com/hands-free-vim/cursorless.nvim) repo is part of the larger cursorless monorepo, and is currently part of a pending PR to that monorepo only. If you'd like to send a PR to `cursorless.nvim`, please send a PR against the `nvim-talon` branch of this [repo](https://github.com/saidelike/cursorless).
+The source of truth for `cursorless.nvim` lives in the [Cursorless monorepo](https://github.com/cursorless-dev/cursorless/). We automatically push to the [cursorless.nvim](https://github.com/hands-free-vim/cursorless.nvim) repo in CI. If you'd like to contribute to `cursorless.nvim`, please open a PR in the [Cursorless monorepo](https://github.com/cursorless-dev/cursorless/).
 
 ## Frequently asked questions