feat: findNvim({ paths: ..., dirs: ...}) #400

Problem:
Apps such as https://github.com/vscode-neovim/vscode-neovim use
`findNvim` to find Nvim on the user's system, but:

- they also support user settings to explicitly set a path.
- the app may want to search other directories besides the default ones.

Since `findNvim` currently doesn't allow the caller to provide extra
paths/directories, consumers such as vscode-neovim have to re-invent
their own way to validate those extra paths/directories, which is
redundant with what `findNvim` already does.

Solution:
Introduce `paths: string[]` and `dirs: string[]` options to `findNvim`.

Author: gjf7

packages/neovim/src/utils/findNvim.test.ts

@@ -1,10 +1,26 @@
 /* eslint-env jest */
+import { join } from 'node:path';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { findNvim, exportsForTesting, FindNvimResult } from './findNvim';
 
 const parseVersion = exportsForTesting.parseVersion;
 const compareVersions = exportsForTesting.compareVersions;
+const normalizePath = exportsForTesting.normalizePath as (p: string) => string;
 
 describe('findNvim', () => {
+  const testDir = join(process.cwd(), 'test-dir');
+  const nvimExecutablePath = normalizePath(
+    join(testDir, process.platform === 'win32' ? 'nvim.exe' : 'nvim')
+  );
+
+  beforeAll(() => {
+    mkdirSync(testDir, { recursive: true });
+    writeFileSync(nvimExecutablePath, 'fake-nvim-executable');
+  });
+
+  afterAll(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
   it('parseVersion()', () => {
     expect(parseVersion('0.5.0-dev+1357-g192f89ea1')).toEqual([
       0,
@@ -119,4 +135,30 @@ describe('findNvim', () => {
       error: undefined,
     });
   });
+
+  it('searches in additional custom paths', () => {
+    const customPaths = [
+      join(process.cwd(), 'package.json'),
+      '/custom/path/to/nvim',
+      '/another/custom/path',
+    ].map(normalizePath);
+    const nvimRes = findNvim({ paths: customPaths });
+
+    expect(nvimRes.matches.length).toBeGreaterThanOrEqual(1);
+
+    expect(nvimRes.invalid.length).toBe(3);
+
+    const invalidPaths = nvimRes.invalid.map(i => i.path);
+    expect(invalidPaths).toEqual(customPaths);
+  });
+
+  it('searches in additional custom dirs', () => {
+    const customDirs = [testDir, '/non/existent/dir'].map(normalizePath);
+    const nvimRes = findNvim({ dirs: customDirs });
+
+    expect(nvimRes.matches.length).toBeGreaterThanOrEqual(1);
+
+    expect(nvimRes.invalid.length).toBe(1);
+    expect(nvimRes.invalid[0].path).toBe(nvimExecutablePath);
+  });
 });

packages/neovim/src/utils/findNvim.ts

@@ -35,6 +35,23 @@ export type FindNvimOptions = {
    * (Optional) Stop searching after found a valid match
    */
   readonly firstMatch?: boolean;
+  /**
+   * (Optional) Additional specific file paths to check for Nvim executables.
+   * These paths will be checked before searching `dirs`.
+   * Useful for allowing users to specify exact Nvim executable locations.
+   *
+   * Example: ['/usr/local/bin/nvim', '/opt/homebrew/bin/nvim']
+   */
+  readonly paths?: string[];
+  /**
+   * (Optional) Additional directories to search for Nvim executables.
+   * These directories will be searched after checking `paths`
+   * but before searching `$PATH` and other default locations.
+   * Useful for including non-standard installation directories.
+   *
+   * Example: ['/opt/neovim/bin', '/home/user/custom/bin']
+   */
+  readonly dirs?: string[];
 };
 
 export type FindNvimResult = {
@@ -117,13 +134,14 @@ function compareVersions(a: string, b: string): number {
   return 0;
 }
 
-function getPlatformPaths() {
+function normalizePath(path: string): string {
+  return normalize(windows ? path.toLowerCase() : path);
+}
+
+function getPlatformSearchDirs(): Set<string> {
   const paths = new Set<string>();
   const { PATH, USERPROFILE, LOCALAPPDATA, PROGRAMFILES, HOME } = process.env;
 
-  const normalizePath = (path: string) =>
-    normalize(windows ? path.toLowerCase() : path);
-
   PATH?.split(delimiter).forEach(p => paths.add(normalizePath(p)));
 
   // Add common Neovim installation paths not always in the system's PATH.
@@ -147,6 +165,7 @@ function getPlatformPaths() {
       paths.add(normalizePath(`${PROGRAMFILES} (x86)/WinGet/Packages`));
     }
   } else {
+    // Common paths for Unix-like systems
     [
       '/usr/local/bin',
       '/usr/bin',
@@ -170,15 +189,24 @@ function getPlatformPaths() {
  * @param opt.minVersion See {@link FindNvimOptions.minVersion}
  * @param opt.orderBy See {@link FindNvimOptions.orderBy}
  * @param opt.firstMatch See {@link FindNvimOptions.firstMatch}
+ * @param opt.paths See {@link FindNvimOptions.paths}
+ * @param opt.dirs See {@link FindNvimOptions.dirs}
  */
 export function findNvim(opt: FindNvimOptions = {}): Readonly<FindNvimResult> {
-  const paths = getPlatformPaths();
+  const platformDirs = getPlatformSearchDirs();
+  const nvimExecutable = windows ? 'nvim.exe' : 'nvim';
+  const normalizedPathsFromUser = (opt.paths ?? []).map(normalizePath);
+
+  const allPaths = new Set<string>([
+    ...normalizedPathsFromUser,
+    ...(opt.dirs ?? []).map(dir => normalizePath(join(dir, nvimExecutable))),
+    ...[...platformDirs].map(dir => join(dir, nvimExecutable)),
+  ]);
 
   const matches = new Array<NvimVersion>();
   const invalid = new Array<NvimVersion>();
-  for (const path of paths) {
-    const nvimPath = join(path, windows ? 'nvim.exe' : 'nvim');
-    if (existsSync(nvimPath)) {
+  for (const nvimPath of allPaths) {
+    if (existsSync(nvimPath) || normalizedPathsFromUser.includes(nvimPath)) {
       try {
         accessSync(nvimPath, constants.X_OK);
         const nvimVersionFull = execFileSync(nvimPath, [
@@ -245,5 +273,6 @@ if (process.env.NODE_ENV === 'test') {
   exportsForTesting = {
     parseVersion,
     compareVersions,
+    normalizePath,
   };
 }