fix: deprecate useHttpgd setting (#1733)

Author: eitsupi

CHANGELOG.md

@@ -15,7 +15,7 @@
 * feat: evaluate params from YAML header in Rmd files before running code
 * feat: check sess package version and prompt for update
 * feat(session): implement file-based reconnection and suppress verbose logs
-* feat(plot): new `r.plot.backend` enum setting for finer-grained control of the preferred plotting backend, including integration with the lightweight `jgd` graphics device (default if installed). `r.plot.useHttpgd` is still respected, but may be deprecated in a future release.
+* feat(plot): new `r.plot.backend` enum setting for finer-grained control of the preferred plotting backend, including integration with the lightweight `jgd` graphics device (default if installed). `r.plot.useHttpgd` is deprecated in favor of `r.plot.backend`; it remains supported for compatibility with existing configurations but will be removed in a future release.
 * feat(term): new `r.rterm.preferredConsoles` enum setting enables for string-based R console selection (`"R"` (default), `"arf"`, and/or `"radian"`), automatically resolved against the user's `PATH`. `r.term.<os>` is still respected (and prioritized) if provided.
 * feat(dataview): keep one viewer per data name, refreshing the existing viewer on repeated `View()` calls
 * feat(dataview): load data rows on demand while scrolling, with support for Arrow and Polars DataFrames

package.json

@@ -1787,7 +1787,7 @@
         },
         "r.plot.devArgs": {
           "type": "object",
-          "markdownDescription": "The supplementary arguments for the rendering device (e.g., `png()` or `svglite()`) used by the standard plot viewer. Note that width and height are now handled dynamically by the responsive viewer and will be overridden. Requires `#r.plot.useHttpgd#` to be set to `false`. \n\nChanges the option `sess.devArgs` in R.",
+          "markdownDescription": "Supplementary arguments for the rendering device (for example, `png()` or `svglite()`) used by the `standard` plot backend. This setting is ignored by the `httpgd` and `jgd` backends. Width and height are managed dynamically by the responsive viewer and will be overridden.\n\nChanges the option `sess.devArgs` in R.",
           "default": {
             "width": 800,
             "height": 1200
@@ -1821,7 +1821,9 @@
         "r.plot.useHttpgd": {
           "type": "boolean",
           "default": false,
-          "markdownDescription": "Use the httpgd-based plot viewer instead of the base VSCode-R plot viewer.\n\nRequires the `httpgd` R package version 1.2.0 or later.\n\n**Deprecated:** Use `#r.plot.backend#` instead. When `#r.plot.backend#` is `auto`, setting this to `true` forces httpgd."
+          "markdownDescription": "Legacy compatibility setting for selecting the httpgd plot viewer. When `#r.plot.backend#` is `auto`, setting this to `true` selects the `httpgd` backend. An explicit `#r.plot.backend#` value takes precedence.\n\nRequires the `httpgd` R package version 1.2.0 or later.",
+          "markdownDeprecationMessage": "Deprecated: use `#r.plot.backend#` instead. This setting is retained for compatibility with existing configurations but will be removed in a future release.",
+          "deprecationMessage": "Deprecated: use r.plot.backend instead. This setting is retained for compatibility with existing configurations but will be removed in a future release."
         },
         "r.plot.backend": {
           "type": "string",
@@ -1833,12 +1835,12 @@
             "jgd"
           ],
           "markdownEnumDescriptions": [
-            "Automatic: tries JGD first (if installed), then httpgd, then standard. Respects `#r.plot.useHttpgd#` if set.",
+            "Automatic: tries JGD first (if installed), then httpgd, then standard. Existing `#r.plot.useHttpgd#` configurations remain supported.",
             "Standard static plot viewer (PNG/SVG)",
             "httpgd-based interactive plot viewer (requires `httpgd` R package)",
             "JGD-based interactive plot viewer (requires `jgd` R package)"
           ],
-          "markdownDescription": "Select the plot backend.\n\nWhen set to `auto`, the best available backend is used (JGD if installed, then httpgd, then standard). Setting `#r.plot.useHttpgd#` to `true` forces httpgd."
+          "markdownDescription": "The canonical setting for selecting the plot backend.\n\nWhen set to `auto`, the best available backend is used (JGD if installed, then httpgd, then standard). For compatibility, setting `#r.plot.useHttpgd#` to `true` selects httpgd while this setting remains `auto`; an explicit backend value takes precedence."
         },
         "r.plot.jgd.historyLimit": {
           "type": "number",
@@ -1867,7 +1869,7 @@
             "png",
             "svglite"
           ],
-          "description": "The graphics format to use for the standard plot viewer. Requires `#r.plot.useHttpgd#` to be set to `false`."
+          "markdownDescription": "The graphics format used by the `standard` plot backend. This setting is ignored by the `httpgd` and `jgd` backends."
         },
         "r.plot.defaults.colorTheme": {
           "type": "string",

src/test/suite/terminal.test.ts

@@ -22,8 +22,8 @@ suite('R Terminal', () => {
         sandbox.restore();
     });
 
-    test('makeTerminalOptions sets session watcher environment variables', async () => {
-        // Stub config to enable sessionWatcher with httpgd backend
+    test('makeTerminalOptions respects legacy plot.useHttpgd configurations', async () => {
+        // Leave plot.backend at its default to verify the legacy boolean still selects httpgd.
         const configStub = {
             get: (key: string, defaultValue?: unknown) => {
                 if (key === 'sessionWatcher') {
@@ -57,6 +57,32 @@ suite('R Terminal', () => {
         assert.ok(options.env['R_PROFILE_USER'].endsWith(path.join('R', 'profile.R')));
     });
 
+    test('makeTerminalOptions prefers an explicit plot.backend over legacy plot.useHttpgd', async () => {
+        const configStub = {
+            get: (key: string, defaultValue?: unknown) => {
+                if (key === 'sessionWatcher') {
+                    return true;
+                }
+                if (key === 'plot.backend') {
+                    return 'standard';
+                }
+                if (key === 'plot.useHttpgd') {
+                    return true;
+                }
+                return defaultValue;
+            }
+        };
+        sandbox.stub(util, 'config').returns(configStub as unknown as vscode.WorkspaceConfiguration);
+        sandbox.stub(util, 'getRterm').resolves(process.execPath);
+        sandbox.stub(util, 'promptToInstallSessPackage').resolves();
+
+        const options = await rTerminal.makeTerminalOptions();
+
+        assert.ok(options.env);
+        assert.strictEqual(options.env['SESS_USE_HTTPGD'], 'FALSE');
+        assert.strictEqual(options.env['SESS_PLOT_BACKEND'], 'standard');
+    });
+
     test('makeTerminalOptions does not set session watcher env if disabled', async () => {
         const configStub = {
             get: (key: string) => {