feat: code lens + new "SFDX: Get SOQL Query Plan with Current File" command in commmand palette

Author: daphne-sfdc

packages/salesforcedx-vscode-soql/package.json

@@ -357,6 +357,10 @@
       {
         "command": "sf.data.query.explain.selection",
         "title": "%query_plan_selection_text%"
+      },
+      {
+        "command": "sf.data.query.explain.document",
+        "title": "%query_plan_document_text%"
       }
     ],
     "menus": {
@@ -388,6 +392,10 @@
         {
           "command": "sf.data.query.explain.selection",
           "when": "sf:project_opened && editorHasSelection && sf:has_target_org"
+        },
+        {
+          "command": "sf.data.query.explain.document",
+          "when": "resourceExtname == .soql && sf:has_target_org"
         }
       ],
       "editor/title": [
@@ -466,5 +474,8 @@
         ]
       }
     ]
-  }
+  },
+  "activationEvents": [
+    "onLanguage:soql"
+  ]
 }

packages/salesforcedx-vscode-soql/package.nls.json

@@ -25,5 +25,6 @@
   "soql_walkthrough_step5_alt": "Saving and exporting SOQL query results",
   "data_query_input_text": "SFDX: Execute SOQL Query...",
   "data_query_selection_text": "SFDX: Execute SOQL Query with Currently Selected Text",
-  "query_plan_selection_text": "SFDX: Get SOQL Query Plan with Currently Selected Text"
+  "query_plan_selection_text": "SFDX: Get SOQL Query Plan with Currently Selected Text",
+  "query_plan_document_text": "SFDX: Get SOQL Query Plan with Current File"
 }

packages/salesforcedx-vscode-soql/src/commands/queryPlan.ts

@@ -11,7 +11,7 @@ import * as vscode from 'vscode';
 import { nls } from '../messages';
 import { channelService } from '../services/channel';
 import { getConnection } from '../services/org';
-import { formatErrorMessage, GetQueryAndApiInputs, QueryAndApiInputs } from './queryUtils';
+import { formatErrorMessage, GetDocumentQueryAndApiInputs, GetQueryAndApiInputs, QueryAndApiInputs } from './queryUtils';
 
 class QueryPlanExecutor {
   public async execute(response: ContinueResponse<QueryAndApiInputs>): Promise<void> {
@@ -47,3 +47,12 @@ export const queryPlan = Effect.fn('sf.data.query.explain')(function* () {
   const commandlet = new SfCommandlet(sfProjectPreconditionChecker, new GetQueryAndApiInputs(), new QueryPlanExecutor());
   yield* Effect.promise(() => commandlet.run());
 });
+
+export const queryPlanDocument = Effect.fn('sf.data.query.explain.document')(function* () {
+  const commandlet = new SfCommandlet(
+    sfProjectPreconditionChecker,
+    new GetDocumentQueryAndApiInputs(),
+    new QueryPlanExecutor()
+  );
+  yield* Effect.promise(() => commandlet.run());
+});

packages/salesforcedx-vscode-soql/src/commands/queryUtils.ts

@@ -63,6 +63,35 @@ export class GetQueryAndApiInputs implements ParametersGatherer<QueryAndApiInput
   }
 }
 
+export class GetDocumentQueryAndApiInputs implements ParametersGatherer<QueryAndApiInputs> {
+  public async gather(): Promise<CancelResponse | ContinueResponse<QueryAndApiInputs>> {
+    const editor = vscode.window.activeTextEditor;
+    if (!editor) {
+      return { type: 'CANCEL' };
+    }
+
+    const query = editor.document.getText().replaceAll(/(\r\n|\n)/g, ' ').trim();
+    if (!query) {
+      return { type: 'CANCEL' };
+    }
+
+    const restApi = {
+      api: 'REST' as const,
+      label: nls.localize('REST_API'),
+      description: nls.localize('REST_API_description')
+    };
+
+    const toolingApi = {
+      api: 'TOOLING' as const,
+      label: nls.localize('tooling_API'),
+      description: nls.localize('tooling_API_description')
+    };
+
+    const selection = await vscode.window.showQuickPick([restApi, toolingApi]);
+    return selection ? { type: 'CONTINUE', data: { query, api: selection.api } } : { type: 'CANCEL' };
+  }
+}
+
 /** Formats error messages for better user experience */
 export const formatErrorMessage = (error: unknown): string => {
   let errorString: string;

packages/salesforcedx-vscode-soql/src/commands/soqlCodeLensProvider.ts

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import { CancellationToken, CodeLens, EventEmitter, ExtensionContext, languages, Range, TextDocument } from 'vscode';
+import { nls } from '../messages';
+import { isDefaultOrgSet, onDefaultOrgChange } from '../services/org';
+
+const SOQL_DOCUMENT_SELECTOR = { language: 'soql' };
+
+const provideCodeLenses = async (document: TextDocument, _token: CancellationToken): Promise<CodeLens[]> => {
+  if (document.getText().trim().length === 0 || !(await isDefaultOrgSet())) {
+    return [];
+  }
+  return [
+    new CodeLens(new Range(0, 0, 0, 0), {
+      command: 'sf.data.query.explain.document',
+      title: nls.localize('soql_query_plan_codelens'),
+      tooltip: nls.localize('soql_query_plan_codelens')
+    })
+  ];
+};
+
+export const registerSoqlCodeLensProvider = (context: ExtensionContext): void => {
+  const changeEmitter = new EventEmitter<void>();
+
+  context.subscriptions.push(
+    languages.registerCodeLensProvider(SOQL_DOCUMENT_SELECTOR, {
+      onDidChangeCodeLenses: changeEmitter.event,
+      provideCodeLenses
+    }),
+    onDefaultOrgChange(() => changeEmitter.fire()),
+    changeEmitter
+  );
+};

packages/salesforcedx-vscode-soql/src/index.ts

@@ -10,8 +10,9 @@ import * as Effect from 'effect/Effect';
 import * as Scope from 'effect/Scope';
 import * as vscode from 'vscode';
 import { dataQuery } from './commands/dataQuery';
-import { queryPlan } from './commands/queryPlan';
+import { queryPlan, queryPlanDocument } from './commands/queryPlan';
 import { soqlBuilderToggle } from './commands/soqlBuilderToggle';
+import { registerSoqlCodeLensProvider } from './commands/soqlCodeLensProvider';
 import { soqlOpenNewBuilder, soqlOpenNewTextEditor } from './commands/soqlFileCreate';
 import { SOQLEditorProvider } from './editor/soqlEditorProvider';
 import { startLanguageClient, stopLanguageClient } from './lspClient/client';
@@ -43,6 +44,7 @@ export const activateEffect = Effect.fn(`activation:${EXTENSION_NAME}`)(function
   yield* Effect.sync(() => {
     context.subscriptions.push(SOQLEditorProvider.register(context));
     QueryDataViewService.register(context);
+    registerSoqlCodeLensProvider(context);
   });
 
   const registerCommand = api.services.registerCommandWithRuntime(getSoqlRuntime());
@@ -62,7 +64,8 @@ export const activateEffect = Effect.fn(`activation:${EXTENSION_NAME}`)(function
       ),
       registerCommand('sf.data.query.input', dataQuery),
       registerCommand('sf.data.query.selection', dataQuery),
-      registerCommand('sf.data.query.explain.selection', queryPlan)
+      registerCommand('sf.data.query.explain.selection', queryPlan),
+      registerCommand('sf.data.query.explain.document', queryPlanDocument)
     ],
     { concurrency: 'unbounded' }
   );

packages/salesforcedx-vscode-soql/src/messages/i18n.ts

@@ -34,6 +34,8 @@ export const messages = {
     "ERROR: We can't save the file to the specified directory. Make sure you have write permissions for the directory.",
   data_query_input_text: 'SFDX: Execute SOQL Query...',
   data_query_selection_text: 'SFDX: Execute SOQL Query with Currently Selected Text',
+  soql_query_plan_codelens: 'Get Query Plan',
+  query_plan_document_text: 'SFDX: Get SOQL Query Plan with Current File',
   data_query_success_message: 'Query executed successfully. Found %d records. Results saved to: %s',
   data_query_error_message: 'Error executing query: %s',
   data_query_error_org_expired:

packages/salesforcedx-vscode-soql/src/services/org.ts

@@ -8,7 +8,9 @@
 import type { Connection } from '@salesforce/core';
 import { getServicesApi } from '@salesforce/effect-ext-utils';
 import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
+import * as vscode from 'vscode';
 import { getSoqlRuntime } from './extensionProvider';
 
 /** TargetOrgRef (getDefaultOrgRef) has no requirements */
@@ -23,6 +25,23 @@ export const isDefaultOrgSet = (): Promise<boolean> =>
     })
   );
 
+/**
+ * Calls `listener` whenever the default org changes. Returns a `Disposable` for cleanup.
+ * Skips the initial current value — only fires on subsequent changes.
+ */
+export const onDefaultOrgChange = (listener: () => void): vscode.Disposable => {
+  const abortController = new AbortController();
+  void getSoqlRuntime().runPromise(
+    Effect.gen(function* () {
+      const api = yield* getServicesApi;
+      const ref = yield* api.services.TargetOrgRef();
+      yield* ref.changes.pipe(Stream.runForEach(() => Effect.sync(listener)));
+    }),
+    { signal: abortController.signal }
+  );
+  return new vscode.Disposable(() => abortController.abort());
+};
+
 export const getConnection = (): Promise<Connection> =>
   getSoqlRuntime().runPromise(
     Effect.gen(function* () {