refactor resolvingWorkspaceVars and implement deprecation telemetry tracker

eleanorjboyd · eleanorjboyd · commit 70f4241a4571 · 2025-10-24T11:04:53.000-07:00
diff --git a/src/extension/debugger/configuration/providers/pyramidLaunch.ts b/src/extension/debugger/configuration/providers/pyramidLaunch.ts
@@ -13,7 +13,7 @@ import { EventName } from '../../../telemetry/constants';
 import { DebuggerTypeName } from '../../../constants';
 import { LaunchRequestArguments } from '../../../types';
 import { DebugConfigurationState, DebugConfigurationType } from '../../types';
-import { resolveVariables } from '../utils/common';
+import { resolveWorkspaceVariables } from '../utils/common';
 
 const workspaceFolderToken = '${workspaceFolder}';
 
@@ -73,7 +73,7 @@ export async function validateIniPath(
     if (!selected || selected.trim().length === 0) {
         return error;
     }
-    const resolvedPath = resolveVariables(selected, undefined, folder);
+    const resolvedPath = resolveWorkspaceVariables(selected, undefined, folder);
     if (resolvedPath) {
         if (selected !== defaultValue && !fs.pathExists(resolvedPath)) {
             return error;
diff --git a/src/extension/debugger/configuration/resolvers/base.ts b/src/extension/debugger/configuration/resolvers/base.ts
@@ -12,7 +12,7 @@ import { getWorkspaceFolders, getWorkspaceFolder as getVSCodeWorkspaceFolder } f
 import { AttachRequestArguments, DebugOptions, LaunchRequestArguments, PathMapping } from '../../../types';
 import { PythonPathSource } from '../../types';
 import { IDebugConfigurationResolver } from '../types';
-import { resolveVariables } from '../utils/common';
+import { resolveWorkspaceVariables } from '../utils/common';
 import { getProgram } from './helper';
 import { getSettingsPythonPath, getInterpreterDetails } from '../../../common/python';
 import { getOSType, OSType } from '../../../common/platform';
@@ -96,7 +96,7 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
             return;
         }
         if (debugConfiguration.envFile && (workspaceFolder || debugConfiguration.cwd)) {
-            debugConfiguration.envFile = resolveVariables(
+            debugConfiguration.envFile = resolveWorkspaceVariables(
                 debugConfiguration.envFile,
                 (workspaceFolder ? workspaceFolder.fsPath : undefined) || debugConfiguration.cwd,
                 undefined,
@@ -118,7 +118,7 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
                 : await getSettingsPythonPath(workspaceFolder);
             debugConfiguration.pythonPath = interpreterPath ? interpreterPath[0] : interpreterPath;
         } else {
-            debugConfiguration.pythonPath = resolveVariables(
+            debugConfiguration.pythonPath = resolveWorkspaceVariables(
                 debugConfiguration.pythonPath ? debugConfiguration.pythonPath : undefined,
                 workspaceFolder?.fsPath,
                 undefined,
@@ -137,7 +137,7 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
             debugConfiguration.python = debugConfiguration.pythonPath;
         } else {
             this.pythonPathSource = PythonPathSource.launchJson;
-            debugConfiguration.python = resolveVariables(
+            debugConfiguration.python = resolveWorkspaceVariables(
                 debugConfiguration.python ?? debugConfiguration.pythonPath,
                 workspaceFolder?.fsPath,
                 undefined,
@@ -194,7 +194,7 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
         } else {
             // Expand ${workspaceFolder} variable first if necessary.
             pathMappings = pathMappings.map(({ localRoot: mappedLocalRoot, remoteRoot }) => {
-                const resolvedLocalRoot = resolveVariables(mappedLocalRoot, defaultLocalRoot, undefined);
+                const resolvedLocalRoot = resolveWorkspaceVariables(mappedLocalRoot, defaultLocalRoot, undefined);
                 return {
                     localRoot: resolvedLocalRoot || '',
                     // TODO: Apply to remoteRoot too?
diff --git a/src/extension/debugger/configuration/resolvers/launch.ts b/src/extension/debugger/configuration/resolvers/launch.ts
@@ -8,7 +8,7 @@ import { getOSType, OSType } from '../../../common/platform';
 import { getEnvFile } from '../../../common/settings';
 import { DebuggerTypeName } from '../../../constants';
 import { DebugOptions, DebugPurpose, LaunchRequestArguments } from '../../../types';
-import { resolveVariables } from '../utils/common';
+import { resolveWorkspaceVariables } from '../utils/common';
 import { BaseConfigurationResolver } from './base';
 import { getDebugEnvironmentVariables, getProgram } from './helper';
 import { getConfiguration } from '../../../common/vscodeapi';
@@ -83,7 +83,7 @@ export class LaunchConfigurationResolver extends BaseConfigurationResolver<Launc
             debugConfiguration.cwd = workspaceFolder.fsPath;
         }
         if (typeof debugConfiguration.envFile !== 'string' && workspaceFolder) {
-            debugConfiguration.envFile = resolveVariables(
+            debugConfiguration.envFile = resolveWorkspaceVariables(
                 getEnvFile('python', workspaceFolder),
                 workspaceFolder.fsPath,
                 undefined,
diff --git a/src/extension/debugger/configuration/utils/common.ts b/src/extension/debugger/configuration/utils/common.ts
@@ -8,36 +8,63 @@
 
 import { Uri, WorkspaceFolder } from 'vscode';
 import { getWorkspaceFolder } from '../../../common/vscodeapi';
+import { sendTelemetryEvent } from '../../../telemetry';
+import { EventName } from '../../../telemetry/constants';
 
 /**
  * @returns whether the provided parameter is a JavaScript String or not.
  */
 function isString(str: any): str is string {
-    if (typeof str === 'string' || str instanceof String) {
-        return true;
-    }
-
-    return false;
+    return typeof str === 'string' || str instanceof String;
 }
 
-export function resolveVariables(
+/**
+ * Resolves VS Code variable placeholders in a string value.
+ *
+ * Specifically handles:
+ * - `${workspaceFolder}` - replaced with the workspace folder path
+ * - `${env.VAR}` or `${env:VAR}` - replaced with empty string
+ * - Unknown variables - left as-is in the original `${variable}` format
+ *
+ * @param value The string containing variable placeholders to resolve
+ * @param rootFolder Fallback folder path to use if no workspace folder is available
+ * @param folder The workspace folder context for variable resolution
+ * @returns The string with variables resolved, or undefined if input was undefined
+ */
+export function resolveWorkspaceVariables(
     value: string | undefined,
     rootFolder: string | Uri | undefined,
     folder: WorkspaceFolder | undefined,
 ): string | undefined {
-    if (value) {
-        const workspaceFolder = folder ? getWorkspaceFolder(folder.uri) : undefined;
-        const variablesObject: { [key: string]: any } = {};
-        variablesObject.workspaceFolder = workspaceFolder ? workspaceFolder.uri.fsPath : rootFolder;
-
-        const regexp = /\$\{(.*?)\}/g;
-        return value.replace(regexp, (match: string, name: string) => {
-            const newValue = variablesObject[name];
-            if (isString(newValue)) {
-                return newValue;
-            }
-            return match && (match.indexOf('env.') > 0 || match.indexOf('env:') > 0) ? '' : match;
-        });
+    if (!value) {
+        return value;
     }
-    return value;
+
+    // opt for folder with fallback to rootFolder
+    const workspaceFolder = folder ? getWorkspaceFolder(folder.uri) : undefined;
+    const workspaceFolderPath = workspaceFolder ? workspaceFolder.uri.fsPath : rootFolder;
+
+    // Replace all ${variable} patterns
+    return value.replace(/\$\{([^}]+)\}/g, (match: string, variableName: string) => {
+        // Handle workspaceFolder variable
+        if (variableName === 'workspaceFolder' && isString(workspaceFolderPath)) {
+            // Track usage of this potentially deprecated code path
+            sendTelemetryEvent(EventName.DEPRECATED_CODE_PATH_USAGE, undefined, {
+                codePath: 'workspaceFolder_substitution',
+            });
+            return workspaceFolderPath;
+        }
+
+        // Replace environment variables with empty string
+        if (variableName.startsWith('env.') || variableName.startsWith('env:')) {
+            // Track usage of this potentially deprecated code path
+            sendTelemetryEvent(EventName.DEPRECATED_CODE_PATH_USAGE, undefined, {
+                codePath: 'env_variable_substitution',
+            });
+            return '';
+        }
+
+        // Unknown variables are left unchanged
+        return match;
+    });
 }
diff --git a/src/extension/telemetry/constants.ts b/src/extension/telemetry/constants.ts
@@ -24,4 +24,5 @@ export enum EventName {
     USE_REPORT_ISSUE_COMMAND = 'USE_REPORT_ISSUE_COMMAND',
     DEBUGGER_PYTHON_37_DEPRECATED = 'DEBUGGER_PYTHON_37_DEPRECATED',
     DEBUGGER_SHOW_PYTHON_INLINE_VALUES = 'DEBUGGER_SHOW_PYTHON_INLINE_VALUES',
+    DEPRECATED_CODE_PATH_USAGE = 'DEPRECATED_CODE_PATH_USAGE',
 }
diff --git a/src/extension/telemetry/index.ts b/src/extension/telemetry/index.ts
@@ -691,4 +691,21 @@ export interface IEventNamePropertyMapping {
        "DEBUGGER_SHOW_PYTHON_INLINE_VALUES" : { "owner": "eleanorjboyd" }
      */
     [EventName.DEBUGGER_SHOW_PYTHON_INLINE_VALUES]: never | undefined;
+    /**
+     * Telemetry event sent when potentially deprecated code paths are executed.
+     */
+    /* __GDPR__
+       "deprecated_code_path_usage" : {
+          "codepath" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" }
+       }
+     */
+    [EventName.DEPRECATED_CODE_PATH_USAGE]: {
+        /**
+         * Identifier for the specific deprecated code path that was executed.
+         * Examples: 'workspaceFolder_substitution', 'env_variable_substitution'
+         *
+         * @type {string}
+         */
+        codePath: string;
+    };
 }
diff --git a/src/test/unittest/configuration/providers/pyramidLaunch.unit.test.ts b/src/test/unittest/configuration/providers/pyramidLaunch.unit.test.ts
@@ -12,10 +12,10 @@ import { Uri } from 'vscode';
 import { DebugConfigStrings } from '../../../../extension/common/utils/localize';
 import { MultiStepInput } from '../../../../extension/common/multiStepInput';
 import { DebuggerTypeName } from '../../../../extension/constants';
-import { resolveVariables } from '../../../../extension/debugger/configuration/utils/common';
 import * as pyramidLaunch from '../../../../extension/debugger/configuration/providers/pyramidLaunch';
 import { DebugConfigurationState } from '../../../../extension/debugger/types';
 import * as vscodeapi from '../../../../extension/common/vscodeapi';
+import { resolveWorkspaceVariables } from '../../../../extension/debugger/configuration/utils/common';
 
 suite('Debugging - Configuration Provider Pyramid', () => {
     let input: MultiStepInput<DebugConfigurationState>;
@@ -52,7 +52,7 @@ suite('Debugging - Configuration Provider Pyramid', () => {
     test('Resolve variables (with resource)', async () => {
         const folder = { uri: Uri.parse(path.join('one', 'two')), name: '1', index: 0 };
         workspaceStub.returns(folder);
-        const resolvedPath = resolveVariables('${workspaceFolder}/one.py', undefined, folder);
+        const resolvedPath = resolveWorkspaceVariables('${workspaceFolder}/one.py', undefined, folder);
 
         expect(resolvedPath).to.be.equal(`${folder.uri.fsPath}/one.py`);
     });

Original file line number	Diff line number	Diff line change
`@@ -24,4 +24,5 @@ export enum EventName {`
`24`	`24`	`USE_REPORT_ISSUE_COMMAND = 'USE_REPORT_ISSUE_COMMAND',`
`25`	`25`	`DEBUGGER_PYTHON_37_DEPRECATED = 'DEBUGGER_PYTHON_37_DEPRECATED',`
`26`	`26`	`DEBUGGER_SHOW_PYTHON_INLINE_VALUES = 'DEBUGGER_SHOW_PYTHON_INLINE_VALUES',`
	`27`	`+ DEPRECATED_CODE_PATH_USAGE = 'DEPRECATED_CODE_PATH_USAGE',`
`27`	`28`	`}`