feat(config): support manual Bazel workspace root selection (#687)

* feat(config): add bazel.workspacePath to manually specify workspace

Add a new configuration option `bazel.workspacePath` that allows users
to manually specify the Bazel workspace directory path. This is useful
when:

- Working with multiple MODULE.bazel files in nested directories
- The auto-detection picks the wrong workspace root
- Using local_path_override with multiple repositories

The path can be absolute or relative to the VS Code workspace folder.

Fixes #621

* test: add unit tests for getBazelWorkspaceFolder with workspacePath config

Add tests to verify:
- Auto-detection works when workspacePath is not configured
- Configured absolute path is used correctly
- Configured relative path is resolved correctly
- Invalid configured path falls back to auto-detection
- Configured path takes precedence over nested MODULE.bazel

* fix: handle Bazel roots nested under workspace folders

Prevent parent or unrelated VS Code folders from producing invalid //../... package queries, and resolve tree selections relative to the configured Bazel root.

* chore: fix workspace path lint after rebase

* fix: complete manual workspace path support

* fix: resolve Bazel executable from workspace roots

* test: pin Bazel version for nested module

* test: allow more time for Bazel queries on CI

Workspace-tree integration tests issue several sequential Bazel queries.
On slower CI runners, server startup can exceed 10 seconds and cause
intermittent timeouts, so raise the suite timeout to 30 seconds.

---------

Co-authored-by: Zsi-r <zsr949480148@gmail.com>

Author: Karnabanu

README.md

@@ -38,6 +38,19 @@ this extension does not automatically _fix_ lint warnings during formatting,
 but you can opt into this by enabling the **Bazel: Buildifier Fix on Format**
 setting.
 
+### Selecting the Bazel workspace root
+
+The extension automatically searches upward for a `MODULE.bazel`,
+`REPO.bazel`, `WORKSPACE.bazel`, or `WORKSPACE` file. If that selects the wrong
+root, or if the Bazel root is nested below the folder opened in VS Code, set
+`bazel.workspacePath` to the Bazel root. The value can be an absolute path or a
+path relative to the VS Code workspace folder.
+
+The extension supports one Bazel root per VS Code workspace folder. To work
+with multiple independent Bazel roots, use a VS Code multi-root workspace and
+add each Bazel root as a separate folder; `bazel.workspacePath` can then be set
+independently for each folder.
+
 ### Using a separate output base
 
 By default this extension will use the default output base for running queries. This will cause builds to block queries, potentially causing degraded performance. In Bazel versions since 7.1 it is safe to disable this by changing the `bazel.queriesShareServer` setting to `false`. In earlier versions it can be safely disabled after adding the convenience symlinks to `.bazelignore`, for example:

package-lock.json

@@ -175,6 +175,12 @@
                     "default": true,
                     "markdownDescription": "Whether to enable Buildifier support for formatting and linting Bazel files. When enabled, provides document formatting and lint diagnostics for BUILD, WORKSPACE, and .bzl files."
                 },
+                "bazel.workspacePath": {
+                    "type": "string",
+                    "default": "",
+                    "markdownDescription": "Pins the single Bazel workspace root used for this VS Code workspace folder. The path can be absolute or relative to the VS Code workspace folder. If unset, the extension searches for `MODULE.bazel`, `REPO.bazel`, `WORKSPACE.bazel`, or `WORKSPACE`. To use multiple independent Bazel roots, add each root as a folder in a VS Code multi-root workspace and configure this setting per folder.",
+                    "scope": "resource"
+                },
                 "bazel.pathsToIgnore": {
                     "type": "array",
                     "items": {
@@ -575,7 +581,6 @@
         "protobufjs": "^8.0.1",
         "protobufjs-cli": "^2.5.1",
         "vscode-languageclient": "^10.0.0",
-        "vscode-uri": "^3.0.2",
         "which": "^6.0.0"
     }
-}
+}

package.json

@@ -21,13 +21,19 @@ function fileExistsSync(filename: string): boolean {
  */
 export function checkBazelIsAvailable(): boolean {
   const bazelExecutable = getBazelExecutablePath();
-  const workspaceFolderPath =
-    vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+  const workspaceFolders = vscode.workspace.workspaceFolders ?? [];
 
-  // Check if the program exists as a relative path of the workspace
-  const pathExists = workspaceFolderPath
-    ? fileExistsSync(path.join(workspaceFolderPath, bazelExecutable))
-    : false;
+  // Relative executable paths are evaluated from the directory where Bazel
+  // commands run. Prefer each resolved Bazel root (including a root pinned by
+  // bazel.workspacePath), and retain the VS Code folder as a fallback when no
+  // Bazel workspace can be resolved.
+  const pathExists = workspaceFolders.some((workspaceFolder) => {
+    const workspaceFolderPath = workspaceFolder.uri.fsPath;
+    const bazelWorkspacePath = getBazelWorkspaceFolder(workspaceFolderPath);
+    return fileExistsSync(
+      path.resolve(bazelWorkspacePath ?? workspaceFolderPath, bazelExecutable),
+    );
+  });
 
   if (!pathExists) {
     try {

src/bazel/bazel_availability.ts

@@ -14,8 +14,9 @@
 
 import * as fs from "fs";
 import * as path from "path";
+import * as vscode from "vscode";
 import { blaze_query } from "../protos";
-import { getPathsToIgnore } from "../extension/configuration";
+import { getPathsToIgnore, getWorkspacePath } from "../extension/configuration";
 import { logError } from "../extension/logger";
 import { BazelQuery } from "./bazel_query";
 
@@ -138,10 +139,99 @@ function findAncestorFile(
   return undefined;
 }
 
+/**
+ * Resolves the manually configured workspace path to an absolute path.
+ *
+ * @param fsPath The path to a file, used to determine the VS Code workspace folder.
+ * @returns The resolved absolute workspace path, or undefined if not configured or invalid.
+ */
+function resolveConfiguredWorkspacePath(fsPath: string): string | undefined {
+  const uri = vscode.Uri.file(fsPath);
+  const workspaceFolder = vscode.workspace.getWorkspaceFolder(uri);
+  const configuredPath = getWorkspacePath(uri);
+
+  if (!configuredPath) {
+    return undefined;
+  }
+
+  let resolvedPath: string;
+
+  // Check if it's an absolute path
+  if (path.isAbsolute(configuredPath)) {
+    resolvedPath = configuredPath;
+  } else if (workspaceFolder) {
+    // Resolve relative path from VS Code workspace folder
+    resolvedPath = path.join(workspaceFolder.uri.fsPath, configuredPath);
+  } else {
+    // No workspace folder, try to resolve from the file's directory
+    resolvedPath = path.resolve(path.dirname(fsPath), configuredPath);
+  }
+
+  // Verify the path exists and is a directory.
+  try {
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isDirectory()) {
+      logError(
+        "Configured Bazel workspace path is not a directory",
+        false,
+        `Path: ${resolvedPath}`,
+      );
+      return undefined;
+    }
+  } catch {
+    logError(
+      "Configured Bazel workspace path does not exist",
+      false,
+      `Path: ${resolvedPath}`,
+    );
+    return undefined;
+  }
+
+  const candidateIsInWorkspace =
+    getBazelWorkspaceRelativePath(resolvedPath, fsPath) !== undefined;
+  let candidateContainsWorkspace = false;
+  try {
+    candidateContainsWorkspace =
+      fs.statSync(fsPath).isDirectory() &&
+      getBazelWorkspaceRelativePath(fsPath, resolvedPath) !== undefined;
+  } catch {
+    // A nonexistent candidate cannot contain the configured workspace.
+  }
+  if (!candidateIsInWorkspace && !candidateContainsWorkspace) {
+    return undefined;
+  }
+
+  const workspaceFiles = [
+    "MODULE.bazel",
+    "REPO.bazel",
+    "WORKSPACE.bazel",
+    "WORKSPACE",
+  ];
+  for (const file of workspaceFiles) {
+    try {
+      fs.accessSync(path.join(resolvedPath, file), fs.constants.F_OK);
+      return resolvedPath;
+    } catch {
+      // File not found, continue.
+    }
+  }
+
+  logError(
+    "Configured Bazel workspace path has no workspace marker file",
+    false,
+    `Path: ${resolvedPath}`,
+    `Expected one of: ${workspaceFiles.join(", ")}`,
+  );
+  return undefined;
+}
+
 /**
  * Search for the path to the directory that has the Bazel WORKSPACE file for
  * the given file.
  *
+ * If a workspace path is manually configured via `bazel.workspacePath`, it will
+ * be used instead of auto-detection.
+ *
  * If multiple directories along the path to the file have workspace files,
  * the lowest path is returned.
  *
@@ -150,6 +240,13 @@ function findAncestorFile(
  * otherwise undefined.
  */
 export function getBazelWorkspaceFolder(fsPath: string): string | undefined {
+  // First, check if a workspace path is manually configured
+  const configuredWorkspace = resolveConfiguredWorkspacePath(fsPath);
+  if (configuredWorkspace) {
+    return configuredWorkspace;
+  }
+
+  // Fall back to auto-detection
   const workspaceFile = findAncestorFile(fsPath, [
     "MODULE.bazel",
     "REPO.bazel",
@@ -159,6 +256,26 @@ export function getBazelWorkspaceFolder(fsPath: string): string | undefined {
   return workspaceFile ? path.dirname(workspaceFile) : undefined;
 }
 
+/**
+ * Returns a Bazel-compatible path relative to a workspace root.
+ *
+ * If the candidate is outside the workspace root, returns undefined.
+ */
+export function getBazelWorkspaceRelativePath(
+  workspaceRoot: string,
+  candidatePath: string,
+): string | undefined {
+  const relativePath = path.relative(workspaceRoot, candidatePath);
+  if (
+    path.isAbsolute(relativePath) ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`)
+  ) {
+    return undefined;
+  }
+  return relativePath.replace(/\\/g, "/");
+}
+
 /**
  * Finds the nearest Bazel package file (BUILD or BUILD.bazel) for the given file path
  * by searching up the directory tree, but only if it's within the current Bazel workspace.

src/bazel/bazel_utils.ts

@@ -20,7 +20,6 @@ import {
   TextDocument,
   Uri,
 } from "vscode";
-import { Utils } from "vscode-uri";
 import { BazelQuery, BazelWorkspaceInfo, QueryLocation } from "../bazel";
 import { getBazelExecutablePath } from "../extension/configuration";
 import { blaze_query } from "../protos";
@@ -86,7 +85,10 @@ export class BazelGotoDefinitionProvider implements DefinitionProvider {
     const range = document.getWordRangeAtPosition(position, LABEL_REGEX);
     const targetText = document.getText(range);
 
-    const location = await targetToUri(targetText, Utils.dirname(document.uri));
+    const location = await targetToUri(
+      targetText,
+      Uri.file(workspaceInfo.bazelWorkspacePath),
+    );
 
     return location
       ? [

src/definition/bazel_goto_definition_provider.ts

@@ -57,6 +57,19 @@ export function getPathsToIgnore(): string[] {
   return getConfigurationWithDefault<string[]>("bazel", "pathsToIgnore");
 }
 
+/**
+ * Gets the manually specified Bazel workspace path from the workspace
+ * configuration.
+ *
+ * @param scopeUri Optional URI to scope the configuration lookup to a specific
+ * resource.
+ * @returns The manually specified workspace path, or an empty string if not set.
+ */
+export function getWorkspacePath(scopeUri?: vscode.Uri): string {
+  const config = vscode.workspace.getConfiguration("bazel", scopeUri);
+  return (config.get<string>("workspacePath") || "").trim();
+}
+
 export function getStartupOptions(): string[] {
   return getConfigurationWithDefault<string[]>(
     "bazel.commandLine",

src/extension/configuration.ts

@@ -12,13 +12,17 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import * as path from "path";
 import * as vscode from "vscode";
-import { BazelWorkspaceInfo, BazelQuery } from "../bazel";
+import {
+  BazelWorkspaceInfo,
+  BazelQuery,
+  getBazelWorkspaceRelativePath,
+} from "../bazel";
 import {
   getBazelExecutablePath,
   getQueryExpression,
 } from "../extension/configuration";
+import { logError } from "../extension/logger";
 import { blaze_query } from "../protos";
 import { BazelPackageTreeItem } from "./bazel_package_tree_item";
 import { BazelTargetTreeItem } from "./bazel_target_tree_item";
@@ -202,9 +206,26 @@ export class BazelWorkspaceFolderTreeItem implements IBazelTreeItem {
     }
     const bazelWorkspacePath = this.workspaceInfo.bazelWorkspacePath;
     const workspaceFolderPath = this.workspaceInfo.workspaceFolder.uri.fsPath;
-    const relativePath = path
-      .relative(bazelWorkspacePath, workspaceFolderPath)
-      .replace(/\\/g, "/");
+    let relativePath = getBazelWorkspaceRelativePath(
+      bazelWorkspacePath,
+      workspaceFolderPath,
+    );
+    if (relativePath === undefined) {
+      const workspacePathFromFolder = getBazelWorkspaceRelativePath(
+        workspaceFolderPath,
+        bazelWorkspacePath,
+      );
+      if (workspacePathFromFolder === undefined) {
+        logError(
+          "Configured Bazel workspace is unrelated to the VS Code folder",
+          false,
+          `Bazel workspace: ${bazelWorkspacePath}`,
+          `VS Code folder: ${workspaceFolderPath}`,
+        );
+        return [];
+      }
+      relativePath = "";
+    }
 
     const queryExpression = getQueryExpression();
     // When the VS Code folder is a subdirectory of the Bazel workspace,

src/workspace-tree/bazel_workspace_folder_tree_item.ts

@@ -13,8 +13,8 @@
 // limitations under the License.
 
 import * as vscode from "vscode";
-import * as path from "path";
-import { BazelWorkspaceInfo } from "../bazel";
+
+import { BazelWorkspaceInfo, getBazelWorkspaceRelativePath } from "../bazel";
 import { IBazelTreeItem } from "./bazel_tree_item";
 import { BazelWorkspaceFolderTreeItem } from "./bazel_workspace_folder_tree_item";
 import { BazelPackageTreeItem } from "./bazel_package_tree_item";
@@ -331,11 +331,11 @@ export class BazelWorkspaceTreeProvider
       return undefined; // File does not belong to a detected bazel workspace
     }
 
-    const relativeFilePath = path.relative(
-      workspaceFolderVSCode.uri.fsPath,
+    const relativeFilePath = getBazelWorkspaceRelativePath(
+      workspaceFolderTreeItem.getWorkspaceInfo().bazelWorkspacePath,
       fileUri.fsPath,
     );
-    if (!relativeFilePath) {
+    if (relativeFilePath === undefined || relativeFilePath === "") {
       return undefined; // Sanity check, should never happen
     }